Um webhook é uma solicitação HTTP que um serviço envia para uma URL que você registra sempre que um evento específico acontece. Ele permite que seu sistema receba dados à medida que ocorrem, em vez de consultar uma API chamando-a repetidamente para verificar se há algo novo disponível. Em um pipeline de dados, isso significa que um trabalho pode reagir a um evento assim que a fonte o reporta.
A plataforma de pagamento Stripe, por exemplo, envia eventos de webhook para seu endpoint via HTTPS como um payload JSON. Seu endpoint deve aceitar solicitações POST e processar os dados do evento que recebe.
Como Funciona a Entrega de Webhook
A documentação do Stripe mostra a mecânica principal:
- Registro: Você registra uma URL de endpoint. No modo ao vivo, o Stripe exige uma URL HTTPS acessível publicamente.
- Reconhecimento rápido: O endpoint deve retornar um código de status 2xx rapidamente, antes de qualquer lógica complexa que possa causar um tempo limite.
- Tentativas: Se a entrega falhar, o Stripe tenta novamente por até três dias com retrocesso exponencial no modo ao vivo.
- Ordenação: O Stripe não garante que os eventos cheguem na ordem em que foram criados.
Protegendo um Endpoint de Webhook
- Verifique assinaturas: O Stripe assina cada evento com um HMAC usando SHA-256 e coloca a assinatura no cabeçalho
Stripe-Signature. - Bloquear repetições: O payload assinado inclui um timestamp, para que você possa rejeitar eventos que são muito antigos.
- Lidar com duplicatas: Um endpoint pode receber o mesmo evento mais de uma vez. Registre os IDs dos eventos processados e ignore repetições.
- Lista de remetentes permitidos: O Stripe envia webhooks de uma lista publicada de endereços IP que você pode restringir em seu firewall.
Usos Comuns de Webhook
- Código e implantação: O GitHub envia um payload HTTP POST para sua URL para os eventos do repositório aos quais você se inscreveu. Sua documentação lista usos como iniciar builds de CI, atualizar um rastreador de problemas externo, atualizar um espelho de backup e implantar em um servidor de produção.
- Pagamentos: Webhooks do Stripe permitem que você responda a eventos assíncronos, como um banco confirmando um pagamento, um cliente contestando uma cobrança ou um pagamento recorrente sendo bem-sucedido.
- Inscreva-se apenas no que você precisa: O Stripe aconselha contra ouvir eventos extras ou todos os eventos, pois isso coloca uma pressão indevida em seu servidor.