Pular para o conteúdo
thiagoetipadrões

Contatos

apps/messaging-streaming/webhook

073 · Comunicação & Mensageria · ≈ 5 min de estudo

Webhook

O gateway de pagamentos notifica o sistema receptor via HTTP POST quando um evento ocorre. O receptor valida a assinatura HMAC antes de processar — padrão de segurança usado por Stripe, PagSeguro e Pagar.me.

passos
6
arquivos
6
teste
1
tecnologias
3
Lógica puraTypeScriptBunElysia
CenárioRelaçõesComparar
Baixar cartão

Cenário

Um gateway de pagamentos notifica o sistema do lojista quando um pagamento é aprovado, recusado ou estornado. O lojista precisa ter certeza de que a chamada veio do gateway, não pode aplicar duas vezes o mesmo evento reenviado nem deixar um evento antigo, entregue atrasado, sobrescrever o estado mais novo.

Planta

Sequência
5/5
POST webhook-id, webhook-timestamp, webhook-signature v11corpo cru, HMAC em tempo constante, janela de 5 min, schema2INSERT evento ON CONFLICT DO NOTHING3200 imediato (duplicata também é 200)4sem resposta ou 5xx → retry com backoff e jitter, mesmo id4xx → falha permanente, sem retryeventos pendentes, efeito e marcação na mesma transação5evento mais antigo que o estado atual é ignoradoGateway de pagamentosReceptor do lojista (Elysia)SQLite do lojistaProcessador
5

5 passos — reproduza para seguir o fluxo

Como funciona

6 passos

Callback HTTP avisa quando algo acontece.

Esconde cada passo: lembre antes de tocar para revelar.

  1. 01

    O gateway assina id.timestamp.corpo com HMAC-SHA256 (formato Standard Webhooks) e envia com timeout curto, depois de checar que o destino não resolve para endereço interno (SSRF)

  2. 02

    O receptor lê o corpo cru (parse: 'none'), compara a assinatura em tempo constante e recusa timestamp fora de 5 minutos — assinatura inválida ou replay é 400, nunca 5xx

  3. 03

    Depois da assinatura, valida o corpo por schema e grava o evento com o id do provedor como chave: reenvio vira no-op e ainda recebe 200

  4. 04

    Responde na hora; o processamento lê a fila de eventos pendentes no SQLite, fora do request

  5. 05

    O efeito e a marcação de processado ficam na mesma transação; o estado só avança com evento mais novo

  6. 06

    No gateway, sem resposta ou 5xx é retentado com backoff exponencial e jitter e o mesmo id; 4xx para na hora

apps/messaging-streaming/webhook

6 arquivos

src/

  • signature_webhook.tsAssinatura e verificação Standard Webhooks, janela anti-replay, rotação de segredo
  • receiver_webhook.tsReceptor Elysia, registro de eventos e fila no SQLite, processador com guarda de ordem
  • sender_webhook.tsEntrega com retry, timeout, sem seguir redirect e guarda contra SSRF
  • config_webhook.tsVariáveis de ambiente validadas no boot
  • receiver_webhook.test.tstesteAssinatura real: reenvio, corpo adulterado, janela nos dois lados, schema, ordem, retry do envio e SSRF
  • demo.tsdemoLojista subindo durante a entrega, eventos fora de ordem, falsificação e replay

Executar · só Bun

  1. cp .env.example .env# variáveis de ambiente
  2. bun install# dependências
  3. bun run demo# roda o cenário
  4. bun run test# testes unitários
Requisitos
Bun

Relações

Onde ele se encaixa

Mapa
  1. Webhook
  • Combina com4
  • Alternativa a1

Por que se relacionam

Combina com

Alternativa a

Teste rápido

Qual destes combina com Webhook?

Próximo projeto · Comunicação & MensageriaSNS Multi-Channel Alerts
Esc

↑ ↓ navegarEnter abrir191 resultados