O que responder

Qualquer 2xx quer dizer recebido, e é só isso que olhamos. Qualquer outra coisa (3xx, 4xx, 5xx, timeout, conexão recusada, certificado inválido) é falha, e a entrega entra no cronograma de retry.

Responda rápido, processe depois

O prazo de uma tentativa é de 10 segundos no total, dos quais até 3 para abrir a conexão. Estourou, conta como falha, mesmo que o seu código tenha processado tudo e só não tenha dado tempo de responder. E aí o webhook volta, e você processa duas vezes.

O padrão que evita isso:

Verifique a assinatura.
Grave o webhook numa fila ou tabela sua.
Responda 200.
Processe fora da requisição.

Emissão de nota, chamada a outra API, e-mail: nada disso cabe dentro da requisição do webhook.

As respostas que costumam dar problema

Redirecionamento não é seguido. Um 301 ou 302 conta como falha. Cadastre a URL final, com https e sem a barra que o seu framework acrescenta por redirecionamento.

Duplicata responde 200. Se o Webhook-Id já foi processado, responda 200 e não faça nada. Responder 409 faz o retry insistir até esgotar e marca como falha uma entrega que deu certo. Veja deduplicação e ordem.

Erro de validação do seu lado não é motivo para 4xx. Se o evento chegou íntegro e assinado mas o seu sistema não sabe tratá-lo, repetir não vai ajudar: grave, responda 200 e investigue. Devolva erro só quando tentar de novo pode dar certo.

O corpo da resposta fica visível

Quando o endpoint só falha

Se o endpoint falha de forma sustentada, ele é desativado automaticamente e deixa de receber entregas, e quem o cadastrou é avisado por e-mail. É proteção dos dois lados: o seu servidor para de receber tráfego que não consegue atender, e as entregas deixam de gastar tentativas contra uma URL fora do ar. Quando o seu servidor voltar, quem cadastrou o endpoint o religa, e as entregas do período podem ser reenviadas.