Configurar webhooks

Publicado em: 16 de julho de 2026 · Última atualização: 12 de setembro de 2026 · Por Marcus Biel

Os webhooks permitem que o Maildroppa notifique outra aplicação quando algo importante acontece na sua conta.

Em vez de consultar repetidamente o Maildroppa para saber se um assinante foi criado, atualizado, teve a inscrição cancelada ou recebeu uma tag, sua aplicação pode receber uma requisição HTTPS logo após o evento ocorrer.

A página “Webhooks” centraliza essa integração, que abrange toda a conta. Nela, é possível criar vários endpoints, escolher os eventos que cada um recebe, adicionar cabeçalhos de autenticação, testar a conexão, consultar tentativas de entrega e reenviar um evento de produção quando necessário.

Como funcionam os webhooks da conta

Um webhook da conta segue este processo:

1. Um evento ocorre no Maildroppa, como a criação de um assinante.
2. O Maildroppa identifica todos os endpoints ativos configurados para receber esse evento.
3. O Maildroppa cria uma entrega para cada endpoint correspondente.
4. O payload JSON é assinado com o segredo de assinatura dos webhooks da conta, chamado “Signing secret”.
5. O Maildroppa envia uma requisição HTTPS POST para a URL salva do endpoint.
6. O endpoint verifica a assinatura, armazena ou processa o evento e retorna uma resposta HTTP.
7. O Maildroppa registra o resultado em “Delivery history”, o histórico de entregas, e faz novas tentativas automaticamente em caso de falhas temporárias.

Se vários endpoints estiverem configurados para receber o mesmo evento, cada um receberá sua própria entrega. O evento de negócio tem o mesmo ID de evento (Event ID) para todos eles, enquanto cada entrega tem seu próprio ID de entrega (Delivery ID).

Os webhooks da conta são diferentes da etapa “Send a webhook” de uma automação. Os webhooks da conta monitoram os eventos selecionados em toda a conta do Maildroppa. Já um webhook de automação só é enviado quando um assinante chega àquela etapa específica. Ambos usam o segredo de assinatura dos webhooks da conta. Por isso, a rotação do segredo afeta todos os receptores de webhooks enviados que verificam assinaturas do Maildroppa.

Como abrir a página de webhooks

Abra “Settings”, expanda “Developers” e selecione “Webhooks”.

A página tem três áreas principais:

• “Signing secret” — segredo de assinatura
• “Endpoints” — endpoints
• “Delivery history” — histórico de entregas do endpoint selecionado

Se houver mais de um endpoint, selecione a linha de um deles para exibir seu histórico de entregas. Se nenhum tiver sido selecionado explicitamente, o Maildroppa mostrará o histórico do primeiro endpoint da lista.

Antes de criar um endpoint

Prepare um receptor no servidor antes de configurar o Maildroppa. O receptor deve:

• Estar disponível por meio de uma URL HTTPS pública.
• Aceitar requisições POST com um corpo application/json.
• Preservar o corpo bruto da requisição até que a assinatura do Maildroppa seja verificada.
• Retornar um status 2xx somente depois que o evento tiver sido aceito com segurança.
• Processar entregas repetidas de forma idempotente, usando o ID do evento.
• Responder rapidamente, em vez de executar tarefas demoradas durante a requisição.

Um padrão confiável é verificar a requisição, armazenar o ID do evento e o payload em uma fila persistente ou em um banco de dados, retornar 200 ou 204 e processar a ação de negócio depois.

Não exponha um computador de desenvolvimento, um endereço de rede local ou um script desprotegido como receptor de webhooks de produção. O Maildroppa aceita apenas destinos HTTPS públicos e verifica o destino novamente ao enviar uma entrega.

Etapa 1: gere o segredo de assinatura

Toda requisição de webhook do Maildroppa é assinada. O receptor usa o segredo de assinatura para verificar se a requisição foi criada pelo Maildroppa e se o corpo não foi alterado durante a transmissão.

No topo da página, o painel “Signing secret” mostra um destes estados:

• Missing — Ainda não existe um segredo de assinatura.
• Ready — Um segredo de assinatura está configurado.
• Loading — O Maildroppa está consultando o status atual.

Clique em “Generate secret” quando o status for “Missing”.

O Maildroppa exibe o novo segredo imediatamente. Ele começa com whsec_. Clique em “Copy” e armazene-o no gerenciador de segredos ou na configuração protegida de ambiente usada pelo receptor.

O valor completo só é exibido imediatamente após a geração ou a rotação. Ao recarregar ou sair da página, o Maildroppa passa a mostrar apenas que existe um segredo e quando ele foi atualizado pela última vez. O segredo armazenado não é exibido novamente.

Se você perder o segredo

Se o receptor não tiver mais o segredo atual, clique em “Rotate secret” e salve o novo valor exibido.

A rotação substitui o segredo anterior imediatamente. O Maildroppa não mantém os dois valores durante um período de transição. Atualize todos os receptores que usam esse segredo da conta antes de enviar novos testes ou depender das entregas de produção.

Novas entregas, tentativas agendadas, testes e reenvios de eventos são assinados com o segredo vigente no momento da requisição HTTP. Isso significa que uma entrega criada antes da rotação pode ser assinada com o novo segredo se a tentativa ocorrer depois.

Trate o segredo como uma senha

Não coloque o segredo de assinatura em código executado no navegador, repositórios públicos, URLs, páginas de erro ou logs comuns da aplicação.

Somente o receptor no servidor precisa do segredo. Se você suspeitar que ele foi exposto, faça a rotação e atualize todos os receptores imediatamente.

Como verificar a assinatura de um webhook

Cada requisição contém estes cabeçalhos do Maildroppa:

• X-Maildroppa-Event-Id — Identifica o evento de negócio.
• X-Maildroppa-Delivery-Id — Identifica esta entrega específica.
• X-Maildroppa-Timestamp — O horário da assinatura em segundos Unix.
• X-Maildroppa-Signature — A assinatura HMAC com indicação de versão.

O Maildroppa também envia:

• Content-Type: application/json
• User-Agent: Maildroppa-Webhooks/1.0

A assinatura tem este formato:

v1=<lowercase hexadecimal HMAC>

O Maildroppa a cria com HMAC-SHA256. O conteúdo assinado é o timestamp, seguido de um ponto e do corpo JSON bruto exato da requisição:

<timestamp>.<raw request body>

Use o segredo de assinatura como chave HMAC.

O exemplo em Node.js a seguir mostra a etapa essencial da verificação. rawBody deve conter os bytes originais da requisição, não um JSON que já tenha sido interpretado e serializado novamente.

import crypto from 'node:crypto';

export function verifyMaildroppaWebhook({ rawBody, timestamp, signature, signingSecret }) {
  const signedPayload = Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), rawBody]);

  const expectedSignature = `v1=${crypto
    .createHmac('sha256', signingSecret)
    .update(signedPayload)
    .digest('hex')}`;

  const received = Buffer.from(signature, 'utf8');
  const expected = Buffer.from(expectedSignature, 'utf8');

  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

Depois de verificar a assinatura, compare também o timestamp com o horário do servidor. Rejeite requisições fora de uma janela curta de tolerância definida para sua infraestrutura, como cinco minutos. Isso reduz o risco de uma requisição válida capturada ser reenviada muito tempo depois.

Só interprete e processe o JSON depois que ambas as verificações forem aprovadas.

Causas comuns de erros de assinatura

A verificação da assinatura costuma falhar por um destes motivos:

• O receptor usa um segredo antigo após a rotação.
• Um middleware interpretou ou alterou o JSON antes do cálculo da assinatura.
• O receptor assina apenas o corpo e omite <timestamp>..
• O timestamp é tratado como uma data formatada, em vez do valor exato do cabeçalho.
• O prefixo v1= é omitido da comparação.
• O HMAC calculado usa outra codificação, em vez de hexadecimal com letras minúsculas.

Registre o ID do evento e o ID da entrega nos logs quando a verificação falhar, mas nunca registre o segredo de assinatura nem valores sensíveis de cabeçalhos personalizados.

Etapa 2: adicione um endpoint

Clique em “Add endpoint” na seção “Endpoints”.

O editor tem quatro partes:

• “Endpoint URL” — URL do endpoint
• “Events” — eventos
• “Custom headers” — cabeçalhos personalizados
• “Active” — status ativo

Novos endpoints começam com “Active” selecionado, e todos os eventos exibidos no editor vêm selecionados. Revise a seleção antes de salvar para que o receptor receba apenas as notificações de que realmente precisa.

Como configurar a URL do endpoint

Informe a URL pública completa que deve receber as requisições do Maildroppa, por exemplo:

https://integrations.example.com/webhooks/maildroppa

A URL deve atender a estes requisitos:

• Deve usar https://.
• Deve conter um nome de host público válido.
• Pode ter até 2.048 caracteres.
• Não pode conter variáveis de template com { ou }.
• Não pode conter nome de usuário ou senha antes do nome de host.
• Não pode conter um fragmento de URL que comece com #.
• Deve usar a porta HTTPS padrão 443.
• Não pode usar localhost, um endereço IP diretamente ou um nome de host que resolva para uma rede privada ou reservada bloqueada.

Parâmetros de consulta são aceitos, mas não coloque chaves de API nem outros segredos na URL. As URLs ficam visíveis na lista de endpoints e nos dados de entrega. Use um cabeçalho personalizado para as credenciais.

O Maildroppa não segue redirecionamentos. Salve o destino HTTPS final, em vez de uma URL que retorne 301, 302, 307 ou 308.

O nome de host do destino é resolvido novamente antes do envio. Se ele passar a resolver para um endereço privado ou bloqueado, será rejeitado mesmo que fosse válido quando o endpoint foi salvo.

Como escolher os eventos

Selecione pelo menos um evento. Um endpoint recebe apenas os tipos de evento selecionados no editor.

A página oferece estas opções de evento:

Subscriber Created — subscriber.created

Enviado quando um assinante é criado na conta do Maildroppa.

Use esse evento para criar o contato correspondente em um CRM, uma plataforma de dados de clientes, um banco de dados interno ou outro sistema que leve as permissões em conta.

Não interprete esse evento como prova de que toda inscrição concluiu o double opt-in, ou seja, a confirmação da inscrição por e-mail. O status do assinante no payload descreve o estado atual.

Subscriber Updated — subscriber.updated

Enviado quando as informações dos campos padrão do assinante ou os valores dos campos personalizados mudam.

Use o objeto completo do assinante no payload como sua representação atual no Maildroppa. Não presuma que apenas uma propriedade específica mudou.

A atribuição e a remoção de tags têm tipos de evento próprios para que possam ser tratadas separadamente.

Subscriber Unsubscribed — subscriber.unsubscribed

Enviado quando o assinante passa para o estado de inscrição cancelada por meio de uma ação de cancelamento de inscrição.

Use esse evento para impedir envios ao contato nos sistemas conectados. Não reinscreva a pessoa automaticamente só porque outro sistema ainda marca o contato como ativo.

Tag Added — subscriber.tag_added

Enviado quando uma tag é atribuída a um assinante.

O payload contém o assinante e a tag envolvidos nessa alteração específica.

Tag Removed — subscriber.tag_removed

Enviado quando uma tag é removida de um assinante.

O payload contém o assinante atualizado e a tag removida. A tag removida é fornecida separadamente, embora não esteja mais presente no array tags atual do assinante.

Form Submitted — form.submitted

Enviado quando um visitante envia um formulário de inscrição do Maildroppa.

Trate esse evento como um sinal de envio de formulário, não como confirmação de que o double opt-in foi concluído. Qualquer fluxo de trabalho que exija uma inscrição confirmada deve continuar respeitando o status atual do assinante e o processo de confirmação.

Use endpoints separados para responsabilidades diferentes

É possível enviar eventos diferentes para sistemas diferentes. Por exemplo:

• Envie eventos de assinantes e tags para um CRM.
• Envie eventos de cancelamento de inscrição para um serviço de supressão de envios.
• Envie eventos de envio de formulário para um pipeline de análise de dados.

Endpoints separados reduzem o tráfego desnecessário e facilitam o diagnóstico de falhas. Cada endpoint tem sua própria seleção de eventos, URL, cabeçalhos personalizados, status de ativação, testes e histórico de entregas.

Como adicionar cabeçalhos personalizados

Cabeçalhos personalizados são opcionais. Use-os quando o receptor exigir uma chave de API, um token bearer, um identificador de tenant ou outro cabeçalho fixo.

Clique em “Add header” e preencha “Header name” com o nome do cabeçalho e “Header value” com o valor. Exemplos adequados incluem:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

É possível adicionar até 20 cabeçalhos personalizados.

Os nomes dos cabeçalhos:

• São obrigatórios.
• Podem conter até 128 caracteres.
• Devem usar caracteres válidos para nomes de cabeçalhos HTTP.
• Devem ser únicos, sem distinção entre maiúsculas e minúsculas.

Os valores dos cabeçalhos:

• São obrigatórios.
• Podem conter até 2.000 caracteres.
• Não podem conter quebras de linha.

Os nomes a seguir são reservados e não podem ser substituídos por um cabeçalho personalizado:

• Content-Type
• Content-Length
• Host
• User-Agent
• Qualquer nome que comece com X-Maildroppa-

Isso impede que um valor personalizado substitua os cabeçalhos de entrega e assinatura do Maildroppa.

Como os segredos dos cabeçalhos são armazenados

O Maildroppa criptografa os valores dos cabeçalhos personalizados antes de armazená-los. Os valores salvos não são devolvidos ao navegador em formato legível.

Ao editar o endpoint posteriormente, o campo de valor mostra “Stored value kept”, indicando que o valor armazenado será mantido. Deixe o campo vazio quando o segredo existente não precisar mudar. Digite um novo valor para substituí-lo.

Se alterar o nome do cabeçalho, informe o valor novamente. O Maildroppa mantém um segredo armazenado apenas enquanto o nome original do cabeçalho não for alterado.

Ao remover uma linha de cabeçalho e salvar o endpoint, esse cabeçalho deixa de ser incluído nas entregas futuras.

Os valores dos cabeçalhos personalizados são tratados como dados sensíveis nas informações armazenadas da requisição. Eles são mascarados, em vez de exibidos no histórico de entregas.

Como definir o endpoint como ativo ou inativo

Deixe “Active” selecionado quando o endpoint estiver pronto para receber eventos imediatamente.

Desmarque essa opção se quiser salvar a configuração sem iniciar as entregas. Você poderá ativar o endpoint depois, na lista de endpoints.

Um endpoint inativo:

• Não recebe novos eventos.
• Não permite o envio de um webhook de teste.
• Continua visível e pode ser editado.
• Mantém o histórico de entregas existente disponível.

Ativar um endpoint não recupera os eventos que ocorreram enquanto ele estava inativo.

Clique em “Save” quando a URL, a seleção de eventos, os cabeçalhos e o status estiverem corretos.

Entenda a lista de endpoints

Cada linha de endpoint mostra:

• A URL de destino.
• Um indicador “Active” ou “Inactive”.
• Os tipos de evento que ele está configurado para receber.
• O número de cabeçalhos personalizados.
• O horário da última atualização do endpoint.

As ações disponíveis são:

• On/Off — Ativa ou desativa o endpoint.
• Test — Envia imediatamente uma requisição de teste para um endpoint ativo.
• Edit — Altera a URL, os eventos, os cabeçalhos ou o status de ativação.
• Delete — Remove permanentemente a configuração do endpoint após a confirmação.

Selecione a parte principal de uma linha para abrir o histórico de entregas daquele endpoint abaixo da lista.

Como as alterações salvas afetam as entregas existentes

Um evento da conta cria uma entrega com uma cópia da URL do endpoint, do payload e dos cabeçalhos personalizados naquele momento.

Editar a URL ou os cabeçalhos personalizados afeta as novas entregas. Uma entrega que já estava na fila mantém o destino original e a configuração de cabeçalhos armazenada.

Alterar os eventos selecionados também afeta apenas os eventos que ocorrerem depois. O Maildroppa não cria entregas retroativamente para tipos de evento que não estavam selecionados no momento em que o evento ocorreu.

O segredo de assinatura funciona de outra forma: ele é lido quando a requisição HTTP é preparada. Por isso, uma entrega pendente ou um reenvio de evento pode usar um segredo de assinatura recém-rotacionado, mesmo que o payload e a cópia da configuração do endpoint tenham sido criados antes.

Como testar um endpoint

Clique em “Test” em um endpoint ativo depois que o receptor e o segredo de assinatura estiverem prontos.

O Maildroppa envia imediatamente uma requisição assinada usando a URL e os cabeçalhos personalizados salvos do endpoint. Alterações não salvas em um editor aberto não fazem parte do teste.

O payload de teste usa o tipo de evento webhook.test e define livemode como false:

{
  "id": "evt_test_example",
  "type": "webhook.test",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": false,
  "data": {
    "message": "This is a test webhook from Maildroppa."
  }
}

Os IDs gerados e o timestamp são diferentes em cada teste real.

Um teste faz exatamente uma tentativa HTTP. Entregas de teste não entram no agendamento de novas tentativas de produção e não podem ser reenviadas.

Depois que a requisição termina, o painel de resultados mostra:

• “Test success” ou “Test failed”, indicando sucesso ou falha no teste
• ID do evento
• Status HTTP, quando uma resposta foi recebida
• Duração
• ID da entrega
• Informações de erro, quando disponíveis
• Um trecho da resposta, quando o receptor retornou um corpo

O teste também aparece no histórico de entregas com o indicador “Test”. Use o filtro “Test” para mostrar apenas requisições de teste.

Entenda o payload de produção

Os eventos de produção da conta usam um envelope JSON comum:

{
  "id": "evt_example",
  "type": "subscriber.created",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {}
}

As propriedades de nível superior têm estes significados:

• id — O ID do evento. Corresponde a X-Maildroppa-Event-Id.
• type — A chave do evento selecionado no editor do endpoint.
• schema_version — A versão do esquema do payload. Use-a para decidir como interpretar o evento.
• created_at — O horário de criação do payload do evento, em UTC.
• livemode — true para eventos de produção e false para eventos de teste.
• data — O conteúdo específico do evento.

Direcione os eventos pelo valor exato de type. Ignore propriedades adicionais de que a integração não precisa, para que adições compatíveis ao payload não causem falhas no receptor.

Payload de eventos de assinante

Os eventos de assinante contêm a representação atual do assinante em data.subscriber:

{
  "id": "evt_example",
  "type": "subscriber.updated",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [
        {
          "id": "b6594e58-0c4b-4138-9ad8-fc4747e076eb",
          "personalization_tag_name": "company",
          "value": "Example Ltd."
        }
      ],
      "tags": [
        {
          "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
          "name": "Customers"
        }
      ]
    }
  }
}

fields e tags são arrays e podem estar vazios. Uma propriedade do assinante também pode ser null quando não houver valor. Por isso, o receptor deve seguir o esquema do payload, em vez de presumir que todos os valores opcionais do perfil estão presentes.

Payload de eventos de tag

Os eventos de tag contêm tanto o assinante quanto a tag que originou o evento:

{
  "id": "evt_example",
  "type": "subscriber.tag_added",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [],
      "tags": []
    },
    "tag": {
      "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
      "name": "Customers"
    }
  }
}

Para subscriber.tag_removed, data.tag continua identificando a tag removida, embora o array tags atual do assinante não a contenha mais.

IDs de evento, IDs de entrega e idempotência

O ID do evento e o ID da entrega têm finalidades diferentes.

ID do evento

O ID do evento identifica o evento de negócio. Ele aparece em:

• A propriedade id de nível superior do payload.
• O cabeçalho X-Maildroppa-Event-Id da requisição.
• O histórico de entregas.

O mesmo evento pode ser enviado a vários endpoints configurados para recebê-lo. Essas entregas compartilham o ID do evento.

Novas tentativas e reenvios manuais também mantêm o ID original do evento. Armazene os IDs dos eventos processados e torne a ação de negócio idempotente, para que uma requisição repetida não crie contatos duplicados, não repita uma ação irreversível nem aplique a mesma alteração duas vezes.

ID da entrega

O ID da entrega identifica um registro de entrega. Ele aparece em:

• O cabeçalho X-Maildroppa-Delivery-Id da requisição.
• O histórico de entregas.

Cada entrega a um endpoint tem seu próprio ID de entrega. Um reenvio manual cria um novo ID de entrega, preservando o ID original do evento.

Use o ID da entrega para rastreamento técnico e suporte. Use o ID do evento para deduplicação no nível de negócio.

Como retornar a resposta HTTP correta

O Maildroppa classifica as respostas da seguinte forma:

• Qualquer resposta 2xx marca a entrega como bem-sucedida.
• Respostas 408 Request Timeout, 429 Too Many Requests e 5xx são falhas temporárias e permitem novas tentativas.
• Falhas de rede que podem ser temporárias geram novas tentativas.
• Redirecionamentos e outras respostas 3xx não são seguidos e são tratados como falhas definitivas.
• Outras respostas 4xx são tratadas como falhas definitivas e não geram novas tentativas.

Retorne 200, 202 ou 204 somente quando o evento tiver sido aceito com segurança. Se o processamento levar tempo, armazene o evento primeiro e retorne uma resposta de sucesso antes de executar o trabalho mais demorado de forma assíncrona.

Não retorne um redirecionamento para outra URL de webhook. Configure a URL final no Maildroppa.

Agendamento automático de novas tentativas

As entregas de produção podem fazer até sete tentativas HTTP.

Após uma falha que permita nova tentativa, o Maildroppa agenda a próxima com estes intervalos:

1. Após a tentativa 1: 1 minuto
2. Após a tentativa 2: 5 minutos
3. Após a tentativa 3: 30 minutos
4. Após a tentativa 4: 2 horas
5. Após a tentativa 5: 12 horas
6. Após a tentativa 6: 24 horas

Se a tentativa 7 ainda apresentar uma falha que permitiria nova tentativa, a entrega passa para o estado “Dead” e nenhuma outra tentativa automática é agendada.

Os intervalos são contados a partir de cada tentativa que falhou. A entrega efetiva pode ocorrer um pouco depois, pois as entregas são processadas de forma assíncrona e também estão sujeitas a limites de proteção do sistema.

Sempre que possível, corrija problemas temporários do receptor antes do horário exibido em “Next retry”. Se as tentativas automáticas tiverem terminado, use “Replay” depois que o receptor voltar a funcionar corretamente.

Entenda o histórico de entregas

O histórico de entregas pertence ao endpoint selecionado no momento. A URL do endpoint aparece no cabeçalho da seção para que você possa confirmar qual histórico está visualizando.

Use estes filtros:

• All — Mostra entregas de produção e de teste.
• Production — Mostra apenas entregas de eventos de produção.
• Test — Mostra apenas testes manuais.

Clique em “Refresh” para consultar o estado mais recente. Não é necessário deixar o histórico aberto enquanto o Maildroppa envia uma entrega ou faz uma nova tentativa.

A página mostra as 50 entregas mais recentes que correspondem ao filtro selecionado.

Colunas de entrega

Cada linha contém:

• Created — Quando o registro da entrega foi criado.
• State — “Pending”, “Success”, “Failed” ou “Dead”.
• HTTP — Status da resposta, número de tentativas, duração e horário da próxima tentativa, quando aplicável.
• Subscriber — O e-mail do assinante, quando o evento está vinculado a um assinante.
• Delivery — Tipo de evento, ID do evento e ID da entrega.
• Actions — “Replay”, quando a entrega permite reenvio.

Se nenhuma requisição HTTP tiver sido feita, a coluna “HTTP” mostrará “No HTTP attempt”. Isso pode acontecer quando o Maildroppa rejeita a requisição antes do envio, por exemplo, porque o segredo de assinatura está ausente ou o destino salvo não pode mais ser usado com segurança.

Quando disponíveis, a linha também mostra um erro em “Error” e um trecho da resposta retornada pelo receptor em “Response excerpt”. Não retorne segredos nem dados pessoais sensíveis no corpo da resposta de um webhook, pois parte dessa resposta pode aparecer no log de entregas da conta.

Estados de entrega

Pending significa que a entrega está aguardando a primeira tentativa ou uma nova tentativa agendada. “Next retry” aparece quando outra tentativa foi agendada.

Success significa que o receptor retornou uma resposta 2xx. Nenhuma outra tentativa automática é necessária.

Failed significa que a entrega terminou com um problema que não permite nova tentativa, foi rejeitada antes de uma tentativa HTTP ou foi interrompida antes do envio.

Dead significa que todas as tentativas automáticas para um problema que permite novas tentativas foram usadas sem receber uma resposta de sucesso.

Retenção do histórico

Os registros de entrega são mantidos por tempo limitado:

• Entregas de produção bem-sucedidas: 30 dias
• Entregas de produção com estado “Failed”: 90 dias
• Entregas de produção com estado “Dead”: 90 dias
• Entregas de teste: 30 dias

Mantenha seus próprios logs de integração se precisar de um histórico de auditoria mais longo. Armazene os IDs dos eventos e das entregas, mas evite armazenar segredos sem necessidade.

Como reenviar um evento de uma entrega

Clique em “Replay” quando quiser tentar novamente uma entrega de produção já concluída.

“Replay” está disponível para entregas de produção nos estados “Success”, “Failed” ou “Dead”. Não está disponível enquanto a entrega estiver em “Pending”, e entregas de teste não podem ser reenviadas.

Um reenvio de evento:

• Cria uma nova entrega no estado “Pending”.
• Cria um novo ID de entrega.
• Mantém o ID original do evento.
• Mantém o tipo de evento e o payload JSON originais.
• Usa a URL de destino original salva e a cópia original dos cabeçalhos personalizados.
• Usa o segredo de assinatura atual quando a nova requisição é preparada.

O reenvio não reconstrói o payload a partir dos dados atuais do assinante. Ele reenvia a cópia original do evento. Isso permite auditar o reenvio e impede que um evento histórico mude de significado silenciosamente.

Apenas um reenvio da mesma entrega de origem pode ficar no estado “Pending” por vez. Aguarde a conclusão desse reenvio antes de solicitar outro.

Certifique-se de que o endpoint esteja em “Active” antes de reenviar. Se o endpoint estiver inativo, o reenvio na fila não poderá ser entregue com sucesso.

Como o receptor pode ter concluído a ação de negócio mesmo sem o Maildroppa ter recebido a resposta de sucesso, o reenvio pode gerar uma requisição duplicada. A deduplicação pelo ID do evento protege o sistema conectado contra a repetição da ação.

Como editar um endpoint

Clique em “Edit” para alterar a URL, a seleção de eventos, os cabeçalhos personalizados ou o status de ativação.

Antes de salvar:

1. Confirme que a nova URL já está disponível.
2. Deixe os campos dos valores de cabeçalhos armazenados em branco quando eles não precisarem mudar.
3. Informe um novo valor para cada cabeçalho renomeado.
4. Revise a seleção de eventos para não remover notificações necessárias por engano.
5. Salve e envie um novo webhook de teste.

Lembre-se de que as entregas na fila mantêm a URL e a cópia dos cabeçalhos personalizados existentes. Teste a nova configuração para as entregas futuras, em vez de presumir que ela altera uma requisição antiga já na fila.

Como desativar um endpoint

Use o interruptor “On/Off” para pausar uma integração sem excluir sua configuração e seu histórico.

Quando um endpoint é colocado em “Off”:

• Novos eventos deixam de entrar na fila para ele.
• Entregas pendentes que ainda não foram reservadas para envio são marcadas como “Failed”.
• “Test” fica desabilitado.
• O endpoint continua disponível para edição e ativação posterior.

Uma requisição já em andamento no momento da desativação ainda pode ser concluída. Consulte o histórico de entregas depois de colocar o endpoint em “Off” se essa distinção for importante para a integração.

Os eventos não recebidos enquanto o endpoint estava inativo não são recuperados quando ele volta para “On”.

Como excluir um endpoint

Clique em “Delete” e confirme o aviso quando o endpoint não deva mais existir.

A exclusão remove o endpoint da página, interrompe entregas futuras de eventos e marca como “Failed” as entregas pendentes que ainda não foram reservadas para envio.

“Delete” não é uma forma de pausar temporariamente. Use o interruptor “On/Off” se houver a possibilidade de precisar da configuração ou do histórico visível novamente.

Antes da exclusão, registre os IDs de evento e de entrega que ainda forem necessários para a auditoria da integração.

Solução de problemas

Não é possível salvar o endpoint

Verifique se:

• A URL começa com https://.
• A URL usa um nome de host público e a porta 443.
• A URL não contém variáveis, informações de login nem fragmento.
• Pelo menos um evento está selecionado.
• Cada cabeçalho personalizado tem um nome único e um valor.
• Os cabeçalhos reservados do Maildroppa e do HTTP não estão sendo usados como nomes de cabeçalhos personalizados.

“Test” está desabilitado

“Test” está disponível apenas para endpoints em “Active”. Coloque o endpoint em “On” ou edite-o e selecione “Active”; depois, salve antes de testar.

O teste mostra “No HTTP attempt”

Gere um segredo de assinatura se o status for “Missing”. Verifique também se o nome de host do destino é público e continua sendo resolvido corretamente.

Uma requisição pode ser rejeitada antes do envio se o segredo, a URL ou os cabeçalhos personalizados forem inválidos, ou se a verificação de segurança do destino falhar.

O receptor retorna 401 ou 403

Verifique o nome do cabeçalho personalizado e a credencial salvos. Edite o endpoint e informe o valor novamente se ele tiver mudado.

Verifique também se o receptor não está confundindo a própria credencial de API com a assinatura do Maildroppa. Um cabeçalho de autorização personalizado e X-Maildroppa-Signature têm finalidades diferentes e podem ser verificados de forma independente.

O receptor retorna um redirecionamento

O Maildroppa não segue redirecionamentos. Substitua a URL do endpoint pela URL HTTPS pública final e teste novamente.

A assinatura não corresponde

Confirme que o receptor:

• Usa o segredo de assinatura atual.
• Usa o valor exato de X-Maildroppa-Timestamp.
• Assina <timestamp>.<raw request body>.
• Usa HMAC-SHA256 e saída hexadecimal com letras minúsculas.
• Compara o valor completo, incluindo v1=.
• Faz a comparação antes que a interpretação do JSON altere o corpo.

O mesmo evento chega mais de uma vez

Isso pode acontecer após uma interrupção de rede, uma nova tentativa ou um reenvio manual. É normal que sistemas de entrega de webhooks ofereçam entrega pelo menos uma vez, em vez de exatamente uma vez.

Use o ID do evento como chave de idempotência. Retorne uma resposta 2xx quando um ID de evento já processado for recebido novamente e nenhuma ação adicional for necessária.

Uma entrega está em “Pending”

Consulte “Next retry” na coluna “HTTP”. Uma falha 408, 429 ou 5xx que permita nova tentativa, ou uma falha temporária de rede, mantém a entrega em “Pending” até a próxima tentativa agendada.

Clique em “Refresh” depois do horário da nova tentativa para carregar o estado mais recente.

Uma entrega está em “Dead”

Todas as tentativas automáticas foram usadas. Primeiro, corrija o receptor, confirme que o endpoint está em “Active”, envie um webhook de teste e depois use “Replay” na entrega de produção.

Checklist recomendado para produção

Antes de depender de um endpoint em produção, confirme todos os itens a seguir:

1. O receptor usa uma URL HTTPS pública estável, com certificado válido.
2. O segredo de assinatura é armazenado fora do código-fonte.
3. A assinatura é verificada com base no corpo bruto sem alterações.
4. Timestamps antigos são rejeitados de acordo com uma tolerância documentada.
5. O receptor armazena e deduplica os IDs dos eventos.
6. O receptor registra os IDs dos eventos e das entregas nos logs para rastreamento.
7. O processamento demorado acontece depois que o evento foi aceito e armazenado de forma persistente.
8. Uma resposta 2xx é retornada apenas para eventos aceitos.
9. As credenciais personalizadas são armazenadas nos cabeçalhos, não na URL.
10. Apenas os tipos de evento necessários estão selecionados.
11. Um webhook de teste é entregue com sucesso e aparece corretamente no histórico de entregas.
12. O monitoramento alerta quando as entregas de produção começam a retornar erros.

Com essas proteções, a página “Webhooks” oferece os dois lados de uma integração confiável: entrega segura de eventos à sua aplicação e um histórico operacional claro dentro do Maildroppa.