O que é Webhook?

O que é um webhook

Webhook é um mecanismo pelo qual um sistema envia uma chamada HTTP para um endereço configurado para comunicar um evento. O sistema de destino recebe a mensagem e executa o tratamento previsto para aquela ocorrência, como atualizar uma matrícula depois da confirmação de pagamento.

Você configura o endereço de recebimento e informa à origem quais eventos deseja acompanhar. Diferentemente do polling, a integração não precisa consultar repetidamente se surgiu uma novidade, embora a entrega ainda possa atrasar ou exigir novas tentativas.

O que a chamada precisa informar

A notificação costuma trazer o tipo do evento e informações que identificam o objeto alterado. O contrato do emissor determina se o corpo contém o objeto completo, uma versão resumida ou apenas um identificador que você deverá usar para consultar os detalhes.

No exemplo abaixo, os nomes dos campos foram inventados para mostrar essa separação. O identificador evt-817 representa a ocorrência, enquanto pag-204 identifica o pagamento relacionado a ela.

1
{
2
  "eventoId": "evt-817",
3
  "tipo": "pagamento.confirmado",
4
  "pagamentoId": "pag-204"
5
}

O processamento pode usar o identificador do evento para reconhecer uma segunda entrega e o identificador do pagamento para localizar a matrícula. Essa associação precisa seguir o contrato real da integração, porque os serviços não usam necessariamente esses nomes ou a mesma forma de identificar repetições.

A origem precisa ser conferida

Um endereço público pode receber chamadas de sistemas diferentes do emissor esperado. A integração deve verificar a autenticação ou assinatura documentada pela origem antes de usar a notificação para alterar um cadastro ou liberar um acesso.

Quando a assinatura depende do corpo original da chamada, transformar o JSON antes da conferência pode invalidar a verificação. Na Stripe, por exemplo, a conferência usa o corpo bruto recebido. O servidor valida esse conteúdo com o header de assinatura e o segredo associado ao endpoint.

Confirmar recebimento e concluir o trabalho

A resposta HTTP comunica ao emissor como a chamada foi recebida, conforme o contrato da integração. Em um processamento demorado, é comum aceitar a notificação para execução posterior, mas essa resposta não pode ser confundida com a conclusão das ações no sistema de destino.

A confirmação enviada antes do registro durável do trabalho cria um intervalo durante o qual uma parada pode deixar a tarefa sem execução. A origem pode considerar a entrega encerrada, por isso a confirmação precisa estar ligada ao registro que permitirá retomar o processamento depois.

Como testar a integração

Além da chamada válida, teste uma assinatura inválida, uma segunda entrega da mesma ocorrência e uma falha no serviço usado pelo workflow. Confira a resposta ao emissor e o resultado no destino, pois cada lado mostra uma parte diferente do processamento.

No n8n, também confira se a origem usa a URL de produção e se a versão pretendida do workflow está publicada. O sucesso de uma chamada na URL de teste demonstra aquele recebimento, mas não comprova que os eventos futuros chegarão pelo endereço usado em produção.

Aplicação na formação

n8n Experts

Webhooks entregam notificações aos sistemas integrados, que precisam conferir a origem e tratar possíveis repetições.

Conhecer a formação →