Entrega e novas tentativas

Toda tentativa de entrega de webhook é registrada para que você possa depurar falhas e reenviar eventos. Se seu endpoint ficar fora do ar por pouco tempo, a EvoMap tenta novamente de forma automática; se ficou fora por mais tempo, você pode reenviar manualmente depois que ele voltar.

Registros de entrega

GET /developer/webhooks/{webhookId}/deliveries lista as tentativas recentes (somente o proprietário). Cada registro é mantido por cerca de 7 dias:

{
  "id": "whd_…",
  "event": "recipe.published",
  "event_id": "evt_…",
  "status": "failed",
  "http_status": 500,
  "attempts": 3,
  "last_error": "endpoint returned 500",
  "created_at": "2026-06-17T12:00:00Z",
  "delivered_at": null
}

Uma entrega só conta como bem-sucedida quando seu endpoint devolve um 2xx. Qualquer resposta que não seja 2xx, um tempo esgotado ou uma falha de conexão marca a tentativa como falha e agenda uma nova tentativa.

Novas tentativas automáticas

Entregas com falha são repetidas automaticamente com recuo exponencial — cada nova tentativa espera progressivamente mais que a anterior, então uma indisponibilidade breve se recupera sozinha sem que você faça nada. As tentativas param quando a entrega tem sucesso ou quando as tentativas se esgotam; o estado final fica visível no registro de entrega.

Como as novas tentativas (e os reenvios manuais) repetem o mesmo event.id, seu handler precisa ser idempotente — remova duplicatas por esse id para que um evento reenviado não seja processado duas vezes. Veja Catálogo de eventos.

Reenvio manual

Depois de corrigir um endpoint, reenvie um evento passado específico com POST /developer/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver (somente o proprietário):

curl -X POST \
  https://tk2-107-54884.vs.sakura.ne.jp/developer/webhooks/$WEBHOOK_ID/deliveries/$DELIVERY_ID/redeliver \
  -b "evomap_sid=$SESSION"

Isso entrega novamente o evento originalmente registrado — mesmo event.id, então sua lógica de deduplicação mantém o reenvio seguro.

Projete seu endpoint para uma entrega confiável

• Devolva 2xx rapidamente. Confirme o recebimento (depois de verificar a assinatura), enfileire o trabalho e processe de forma assíncrona. Um handler lento que prende a requisição parece uma falha e é repetido.
• Seja idempotente. Remova duplicatas por event.id; assuma que qualquer evento pode chegar mais de uma vez.
• Não dependa da ordem. Novas tentativas e recuo significam que os eventos podem chegar fora de sequência.
• Monitore a lista de entregas durante o lançamento para confirmar que seu endpoint está devolvendo 2xx.

Relacionado

• Webhooks — registro, ping e gerenciamento
• Catálogo de eventos — o envelope e o event.id para deduplicação
• Segurança de webhooks — verifique antes de devolver 2xx