Uma URL pública de recebimento pode receber requisições de qualquer pessoa. Um invasor pode enviar um evento fabricado para essa URL, então a requisição precisa de autenticação antes de acionar qualquer trabalho.
Bird usa o esquema de assinatura Standard Webhooks. Ele autentica o identificador do evento e o horário da tentativa junto com o corpo, de modo que alterar qualquer um deles invalida a assinatura.
O que Bird assina?
Bird assina o identificador do evento, o timestamp da tentativa de entrega e o corpo bruto da requisição, unidos por pontos.
Mantenha o corpo da requisição inalterado até verificar a assinatura. Fazer o parse e serializar JSON pode alterar os bytes que Bird assinou.
| Header | O que ele carrega |
|---|---|
webhook-id | O identificador do evento, reutilizado entre tentativas e replays. |
webhook-timestamp | O horário da tentativa como um timestamp Unix em segundos. |
webhook-signature | Uma ou mais assinaturas, separadas por espaços. Cada uma começa com v1,. |
Converta o timestamp de segundos antes de compará-lo com um relógio que reporta milissegundos.
Remova o prefixo whsec_ do segredo do seu endpoint e decodifique o restante em base64 para recuperar os bytes da chave.
Una o identificador, o timestamp e o corpo intacto com pontos. Calcule HMAC-SHA256 sobre essa string usando a chave decodificada. Compare o resultado com cada assinatura fornecida usando uma comparação em tempo constante, cujo tempo de execução não revela quais bytes correspondem.
Por que minha assinatura nunca corresponde?
Um segredo errado ou um corpo de requisição alterado pode fazer toda verificação de assinatura falhar.
Frameworks web frequentemente fazem o parse de JSON antes de o seu handler executar. Serializar esse objeto novamente pode alterar espaços em branco, ordem das chaves ou formatação numérica. O JSON resultante pode significar a mesma coisa e ainda assim produzir uma assinatura diferente.
Configure essa rota para preservar o corpo bruto. Verifique se o segredo pertence a esse endpoint, especialmente após uma implantação ou rotação.
O que meu handler deve rejeitar?
Rejeite uma requisição quando nenhuma assinatura corresponder ou quando o timestamp assinado estiver fora da janela de tempo permitida.
Tente todas as assinaturas em webhook-signature. Durante a rotação de segredo, uma entrega carrega assinaturas de múltiplos segredos válidos. Aceitar qualquer assinatura correspondente permite que os receptores usando qualquer um dos segredos continuem funcionando.
Use uma tolerância de cinco minutos no timestamp para cada lado do seu relógio. Uma requisição capturada dez minutos antes então falha mesmo que sua assinatura esteja inalterada. Mantenha o relógio do servidor preciso para não rejeitar entregas legítimas.
Confira webhook-id contra eventos que você já armazenou. Uma duplicata reconhecida deve receber sucesso sem repetir o trabalho, já que tentar novamente a mesma entrega não adiciona nenhum evento novo.
O que acontece se eu rejeitar uma entrega?
Bird tenta novamente uma entrega que recebe uma resposta de erro ou nenhuma resposta antes do timeout.
Uma resposta 400, por exemplo, registra a rejeição e deixa a entrega elegível para nova tentativa. Todas as respostas não 2xx seguem a política de novas tentativas. O código ajuda você a diagnosticar a falha nos seus logs.
A agenda se estende por aproximadamente 27,5 horas antes de ajustes, dando tempo para corrigir um segredo errado. Novas tentativas de webhooks com falha descreve a agenda e como fazer replay de eventos perdidos depois.
Retorne 2xx somente após ter verificado e armazenado o evento com segurança, ou reconhecido uma duplicata já armazenada. Bird ignora entregas bem-sucedidas durante o replay, então confirmar uma requisição não verificada impede a recuperação por esse mecanismo.
Preciso implementar a verificação eu mesmo?
Você não precisa implementar a verificação sozinho quando usa webhooks.unwrap em um Bird SDK. Passe o corpo bruto e os headers da requisição para ele.
O helper verifica a assinatura e o timestamp antes de retornar o evento decodificado. Sua aplicação ainda desduplica por webhook-id, porque é ela que mantém o registro do trabalho concluído.
Uma biblioteca de verificação Standard Webhooks compatível pode realizar as mesmas checagens. O guia de webhooks inclui exemplos e uma implementação manual.
Em resumo
Verifique os bytes originais.
Fazer o parse e serializar JSON pode alterar os bytes que Bird assinou. Preserve o corpo bruto para verificação.
Confira o horário além da assinatura.
Uma tolerância de cinco minutos no timestamp limita a reutilização de requisições capturadas. Desduplique eventos armazenados por webhook-id separadamente.
Tente todas as assinaturas fornecidas.
A rotação cria assinaturas sobrepostas. Uma correspondência com qualquer assinatura válida permite que a implantação continue.
Confirme apenas eventos verificados e armazenados.
Bird tenta novamente respostas não 2xx e ignora entregas bem-sucedidas durante o replay. Retorne sucesso para duplicatas já armazenadas sem repetir o trabalho delas.