Webhook vs API: quando buscar e quando receber

Webhook vs API

Webhook vs API: push vs pull, assinaturas, retries | We.Inc

Webhook vs API explicado com uma tabela comparativa, os prós e contras de polling vs push, um verificador de assinatura HMAC no navegador, tratamento de retries e código de receptor idempotente.

Com uma chamada de API, seu código pede dados a outro serviço quando quiser: isso é pull. Com um webhook, o serviço envia um HTTP POST para a sua URL no momento em que algo acontece: isso é push. A maioria das integrações usa os dois, um webhook para saber de uma mudança rapidamente e uma chamada de API para buscar o registro completo e atual.

Requisição de API vs webhook

Requisição de API (pull)
Webhook (push)

Quem inicia
Seu código
O outro serviço

Momento
Quando você pede, ou em um timer de polling
Logo depois do evento

Você precisa de
Uma chave de API e um cliente
Um endpoint HTTPS público

Como provar o remetente
O provedor confere sua chave
Você confere a assinatura do provedor

Quando algo falha
Você vê o erro e tenta de novo
O provedor tenta de novo; você precisa tratar duplicatas

Ideal para
Ler ou alterar dados sob demanda
Reagir a eventos que você não causou

Fazer polling em uma API a cada minuto para ver se um pagamento foi compensado desperdiça requisições e ainda assim chega atrasado. Um webhook inverte a direção, mas também passa a responsabilidade para você: seu endpoint precisa ser público, provar que cada mensagem é genuína, responder rápido e lidar com o mesmo evento chegando duas vezes. Esta página cobre cada uma dessas tarefas com código que você pode copiar.

Registre no provedor uma URL do seu servidor e escolha os eventos que interessam.
O provedor assina o corpo de cada evento com um segredo compartilhado e faz um POST para essa URL.
Seu endpoint recalcula a assinatura sobre o corpo bruto, rejeita as que não batem e responde 2xx rapidamente.
Um job em segundo plano faz o trabalho de verdade, pulando qualquer id de evento que já tenha processado.

Verifique sobre os bytes brutos do corpo. Fazer parse e serializar o JSON de novo muda os espaços e quebra a assinatura.
Compare assinaturas com uma função de tempo constante como crypto.timingSafeEqual, nunca com ===.
Guarde os ids de eventos processados com uma restrição de unicidade, para que um retry ou uma duplicata vire uma operação inofensiva que não faz nada.
Não presuma que os eventos chegam em ordem. Busque o objeto atual na API quando a ordem importar.
Mantenha um job de reconciliação lento que faz polling na API uma vez por dia, para pegar qualquer evento que nunca chegou.

Perguntas frequentes

Um webhook é um tipo de API?

De forma geral, sim. É uma requisição HTTP com um corpo JSON, só que enviada na direção oposta. Às vezes chamam de API reversa. A diferença que importa é quem inicia a conversa e quem precisa estar online para recebê-la.

Devo fazer polling ou usar webhooks?

Use webhooks quando o provedor os oferece para os eventos de que você precisa e você consegue hospedar um endpoint HTTPS público. Faça polling quando não houver webhook, quando você estiver atrás de um firewall ou para poucas verificações em que um minuto de atraso não faz diferença.

Como saber se um webhook veio mesmo do provedor?

A maioria dos provedores envia em um header um HMAC SHA-256 do corpo, calculado com um segredo que só você e eles conhecem. O GitHub, por exemplo, usa X-Hub-Signature-256 com o prefixo sha256=; o Stripe usa Stripe-Signature com um timestamp. Recalcule e compare antes de confiar em qualquer coisa.

O que acontece se meu endpoint estiver fora do ar?

A maioria dos provedores tenta reenviar entregas que falharam com intervalos cada vez maiores, por um período que depende do provedor. O Stripe, por exemplo, continua tentando enviar eventos de produção por até três dias. Depois disso, o evento só fica disponível pela API ou pelo painel deles.

Por que um handler de webhook deve responder antes de fazer o trabalho?

Os provedores esperam pouco tempo por uma resposta. Se o seu código envia e-mails ou chama outros serviços antes, a entrega pode estourar o tempo e ser reenviada, mesmo que você já tenha agido. Coloque o job na fila, retorne 200 e processe depois.

Pull: chamando uma API

Uma requisição de API é uma pergunta que seu código faz: me dê o pedido 42, liste os cadastros de hoje, crie este cliente. Você escolhe quando perguntar e recebe uma resposta na hora, incluindo um erro claro se algo deu errado.
O custo é que você só fica sabendo das mudanças quando pergunta. Para perceber eventos novos, você precisa fazer polling em um timer, e a maioria das consultas volta vazia.

Push: recebendo um webhook

Um webhook é o provedor chamando você. Quando o evento acontece, ele faz um POST com uma descrição em JSON para a URL que você registrou, geralmente em poucos segundos.
Como qualquer pessoa na internet pode fazer POST nessa URL, o corpo não é confiável até a assinatura ser validada. Como redes falham, o mesmo evento pode chegar mais de uma vez ou fora de ordem. Um bom receptor é construído para as duas coisas desde o primeiro dia.

Usando os dois juntos

Um padrão comum e robusto trata o webhook como uma campainha. Ele avisa qual objeto mudou; aí você chama a API para ler o estado atual desse objeto e agir. Isso evita problemas de ordem e payloads desatualizados, e um polling diário pega o que a campainha deixou passar.

Um receptor de webhook que confere a assinatura

Node e Express: HMAC SHA-256 sobre o corpo bruto

express.raw mantém o corpo como bytes para que a assinatura bata. Este formato de header segue a convenção sha256= do GitHub; adapte o nome do header para outros provedores.

Lidando com retries e duplicatas

Um índice único no id do evento faz uma segunda entrega falhar no insert, então o trabalho roda uma vez só, não importa quantas vezes o evento chegue.

Registrar cada id de evento uma vez (PostgreSQL)

ON CONFLICT DO NOTHING não retorna linha para uma duplicata, e seu código trata isso como já processado.

A alternativa com polling

O polling é mais simples de hospedar, mas é mais lento e gera mais tráfego. Mantenha um cursor para que cada consulta peça só o que é novo.

Verificador de assinatura HMAC SHA-256

Cole um corpo e um segredo para calcular a assinatura que um provedor enviaria e depois cole o header que você recebeu para comparar. Tudo roda no seu navegador com a Web Crypto API; nada é enviado para lugar nenhum.

Corpo bruto da requisição

Segredo do webhook

Assinatura que este corpo deve ter

Header de assinatura que você recebeu (opcional)

Confere: o corpo e o segredo produzem esta assinatura.

Não confere: o corpo mudou, o segredo está errado ou o header usa outro formato.