O que é um webhook?

Quando Bird chama seu endpoint, o receptor deve preservar o evento antes de iniciar qualquer processamento. Um webhook é uma requisição HTTP que um sistema envia para a sua aplicação quando algo acontece. O remetente assina o POST para a URL que você registrou. Seu receptor decide quando o evento foi aceito de forma durável.

Qual a diferença entre um webhook e polling em uma API?

Polling significa que seu app chama uma API periodicamente e verifica se houve mudanças. Um webhook inverte essa direção: o provedor chama seu endpoint quando um evento ocorre, evitando requisições ociosas e permitindo reagir mais rápido.

Webhooks precisam de um endpoint HTTPS público capaz de receber requisições enquanto os eventos são entregues. Polling funciona de qualquer lugar e permite que seu app escolha quando buscar o estado. Use webhooks para notificações em tempo hábil. Use a API para buscar mais detalhes do recurso quando o evento traz apenas identificadores.

Como é uma requisição de webhook?

Uma requisição de webhook é um HTTP POST com headers e um envelope de evento JSON. O evento de entrega de e-mail do Bird tem type, um timestamp de evento e data específicos do tipo:

{
  "type": "email.delivered",
  "timestamp": "2026-06-10T14:30:00Z",
  "data": {
    "email_id": "em_01krdgeqcxet5s7t44vh8rt9mg",
    "recipient_id": "er_01krdgeqcxet5s7t44vh8rt9mg",
    "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
    "recipient": "user@example.com",
    "recipient_role": "to",
    "tags": [{ "name": "category", "value": "welcome" }],
    "metadata": { "order_id": "ord_123" },
    "broadcast_id": null
  }
}

O ID da mensagem é data.email_id. A identidade da entrega é o header webhook-id, que permanece o mesmo quando Bird tenta novamente ou reproduz aquele evento. O timestamp do corpo registra quando o evento ocorreu. O header webhook-timestamp registra esta tentativa de entrega, então os dois timestamps respondem perguntas diferentes. Consulte os campos de evento de e-mail para payloads específicos de cada evento.

Como verificar a assinatura de um webhook?

Preserve os bytes brutos da requisição e verifique a assinatura antes de fazer parse ou armazenar o evento. O SDK do Bird verifica os headers webhook-id, webhook-timestamp e webhook-signature. Ele aplica a tolerância de timestamp automaticamente. Use o guia de assinatura em vez de escrever um segundo verificador.

Se você precisa entender a entrada de assinatura, Bird usa {webhook-id}.{webhook-timestamp}.{raw request body}. O segredo do endpoint começa com whsec_; remova esse prefixo e decodifique o restante em base64 antes de computar HMAC-SHA256. Durante a rotação de segredo, o header de assinatura pode conter vários valores v1, separados por espaço, então aceite um valor correspondente entre os segredos ativos.

Rejeite requisições malformadas, não autenticadas ou expiradas antes de armazená-las. Fazer parse do JSON primeiro pode alterar espaços em branco ou a ordem das chaves, e os bytes deixam de corresponder à mensagem assinada.

Como armazenar e confirmar o recebimento de um webhook?

Persista o evento verificado e seu trabalho durável antes de retornar sucesso. Insira o evento com chave webhook-id. Insira o item de trabalho para um evento novo. Faça commit de ambos em uma transação ou em um design equivalente de inbox e outbox duráveis.

read raw bytes and headers
verify the signature and timestamp with the Bird SDK
begin a durable transaction
  insert the inbox event keyed by webhook-id, unless it already exists
  insert a durable work item for a new event
commit the transaction
return 204
worker processes the persisted event idempotently

Uma duplicata que já está armazenada de forma durável pode receber 204 sem gerar mais trabalho. Retorne não 2xx quando o commit durável falhar, para que Bird tente novamente a entrega. Depois de retornar sucesso, reprocesse o worker local a partir do seu registro durável em vez de esperar que Bird envie o evento novamente.

Essa ordenação é um design de aplicação para a semântica de entrega at-least-once do Bird. Não é uma fila que Bird gerencia para você. O guia de duplicatas e idempotência cobre a decisão de deduplicação em mais detalhes.

Como funcionam as tentativas e o replay de webhooks?

Bird dá a uma entrega normal 15 segundos para receber uma resposta. Qualquer status 2xx é considerado sucesso. Um status não 2xx, redirecionamento ou timeout falha e segue o cronograma de tentativas.

A curva tem 8 tentativas incluindo a requisição inicial. Cada atraso é aplicado com mais ou menos 20% de jitter. Um 429 ou timeout de conexão eleva o atraso base para 60 segundos. Um valor Retry-After positivo é limitado entre esse atraso base e o dobro do base antes do jitter, então a tabela descreve atrasos base e não horários exatos de chegada. Consulte como webhooks com falha são retentados para o caminho de falha.

As entregas não são ordenadas, então não atualize o estado atual da aplicação apenas pela ordem de chegada. Use o timestamp do evento e o estado do seu recurso quando os eventos podem chegar fora de ordem.

Quando uma entrega é perdida, inspecione as tentativas de webhook. Corrija o receptor. Crie um replay de webhook. Bird ignora entregas que o endpoint já recebeu com sucesso. Um replay reutiliza o webhook-id original, então a mesma chave de deduplicação o protege.

O que conectar depois de aprender o básico de webhooks?

Crie um endpoint. Verifique e aceite de forma durável suas entregas assinadas. Inspecione as tentativas de entrega. Reproduza eventos perdidos. Depois use a rotação de segredo para implantar um novo segredo de assinatura sem perder entregas.