Catálogo de eventos
Toda entrega de webhook é um envelope JSON assinado com a mesma forma de nível superior, independentemente do tipo de evento. Assine os tipos que interessam a você ao registrar o webhook; a EvoMap faz POST de um envelope para cada evento correspondente.
O envelope
{
"id": "evt_…",
"type": "recipe.published",
"created": "2026-06-17T12:00:00Z",
"livemode": true,
"data": { "…": "event-specific fields" }
}
| Campo | Tipo | Observações |
|---|---|---|
id | string | Id de evento único (evt_…). Deduplique por ele — um reenvio o repete. |
type | string | O tipo de evento (tabela abaixo). |
created | string | Timestamp ISO-8601 de quando o evento ocorreu. |
livemode | boolean | true para eventos reais; false para eventos produzidos por um cliente em modo de teste. |
data | object | Payload específico do evento — o recurso afetado. |
livemode permite que um único endpoint trate com segurança tanto o tráfego real
quanto o de modo de teste: ramifique com base nele para que um
evento do ambiente de testes nunca toque o estado de produção.
Tipos de evento
| Tipo | Assinável | Dispara quando |
|---|---|---|
recipe.created | ✅ | Um rascunho de receita é criado. |
recipe.published | ✅ | Uma receita entra no pool de valor público. |
recipe.takedown | ✅ | Uma receita publicada é removida. |
ping | — | Uma entrega de teste que você dispara para verificar um endpoint. Não é um tipo assinável. |
Você escolhe entre os tipos assináveis (recipe.created, recipe.published,
recipe.takedown) no array events no momento do registro. O ping é entregue apenas
quando você chama explicitamente o endpoint de ping, então você nunca o assina — mas
seu handler ainda deve aceitá-lo (ele chega assinado, exatamente como um evento real).
O payload data
data carrega o recurso a que o evento se refere — para os tipos recipe.*, a receita
afetada. Trate data como um objeto aberto: leia os campos de que você precisa e
tolere outros adicionais, já que o payload pode ganhar campos ao longo do tempo sem uma
mudança que quebre a compatibilidade. Em caso de dúvida, use o id/type do envelope
para consultar o recurso pela API em vez de depender da
presença de um campo específico de data.
Orientações de tratamento
- Deduplique por
event.id— novas tentativas e reenvios manuais reutilizam o mesmo id. - Ramifique com base em
livemodepara que eventos de teste não alterem dados de produção. - Não presuma ordenação — entregas podem chegar fora de ordem ou passar por novas tentativas; projete handlers idempotentes.
Relacionado
- Webhooks — registre endpoints e assine eventos
- Segurança de webhooks — verifique que cada entrega é autêntica
- Entrega e novas tentativas — o que acontece quando seu endpoint falha