Tema: webhooks
-
A especificação Standard Webhooks versus o cabeçalho HMAC da Shopify e o token de segredo compartilhado do GitLab
A especificação Standard Webhooks define os cabeçalhos webhook-id, webhook-timestamp e webhook-signature, um segredo em base64 com prefixo whsec_ cujos bytes decodificados são a chave HMAC e uma assinatura v1,<base64> sobre "{id}.{timestamp}.{payload}"; os tokens de assinatura do GitLab (GitLab 19.0, disponibilidade geral na 19.1) seguem exatamente esse modelo. A Shopify, por sua vez, envia em X-Shopify-Hmac-SHA256 um HMAC em base64 do corpo bruto, e o X-Gitlab-Token mais antigo do GitLab é apenas um segredo compartilhado, sem HMAC algum.
-
Verificação de assinaturas de requisições do Slack: X-Slack-Signature, janela de replay de 5 minutos e regra dos 3 segundos
O Slack assina as requisições como v0=<HMAC-SHA256 em hexadecimal> da string "v0:{timestamp}:{raw body}" no cabeçalho X-Slack-Signature, junto com X-Slack-Request-Timestamp; o exemplo do próprio Slack rejeita a requisição quando esse timestamp difere do horário local em mais de cinco minutos. Slash commands e payloads interativos também precisam ser confirmados em até três segundos, antes de qualquer processamento lento.
-
Verificação de assinaturas de webhook do Stripe: Stripe-Signature, tolerância de timestamp e rotação de segredo
O Stripe envia um cabeçalho Stripe-Signature no formato t=<timestamp>,v1=<assinatura hex>, calculado como HMAC-SHA256 sobre a string "{timestamp}.{raw body}", usando como chave o segredo completo do endpoint (whsec_). As bibliotecas do Stripe rejeitam por padrão assinaturas com timestamp de mais de cinco minutos (300 segundos), e, enquanto um segredo substituído continua ativo (até 24 horas), o cabeçalho traz um valor v1 para cada segredo ativo.
-
Tratamento idempotente de webhooks: IDs de entrega, cronogramas de retry dos provedores e resposta rápida
Todos os grandes provedores de webhook podem entregar o mesmo evento mais de uma vez e esperam que o receptor deduplique com um identificador próprio de cada um: X-GitHub-Delivery, o id do evento do Stripe, o event_id do Slack com X-Slack-Retry-Num ou o webhook-id do Standard Webhooks. Os cronogramas de retry diferem muito: o GitHub não faz nenhuma retentativa automática (o reenvio manual ou via API reaproveita o ID de entrega), o Stripe faz retentativas por até três dias em modo live e o Slack faz três retentativas em cerca de seis minutos.
-
Verificação de assinaturas de webhooks do GitHub: X-Hub-Signature-256, comparação em tempo constante e IDs de entrega
O GitHub assina cada entrega de webhook com HMAC-SHA256 sobre o corpo bruto da requisição e envia o resultado como sha256=<digest hex> no cabeçalho X-Hub-Signature-256. O receptor deve recalcular o digest a partir dos bytes exatos recebidos, compará-lo com uma função de tempo constante e usar X-GitHub-Delivery para reconhecer eventos reenviados; o antigo X-Hub-Signature (HMAC-SHA1) existe apenas por compatibilidade.
-
A armadilha do corpo bruto: por que parsers de corpo JSON quebram a verificação de assinatura de webhooks
As assinaturas de webhook baseadas em HMAC são calculadas sobre os bytes exatos enviados pelo provedor. Qualquer middleware JSON que faça parse, reordene ou reserialize o corpo antes do seu handler altera esses bytes e invalida a assinatura. Express, FastAPI, Flask, Django e Go exigem, cada um, uma forma específica de capturar o corpo intacto antes do parsing normal ou no lugar dele.
Legível por máquina: JSON