Webhooks

Quando algo acontece na sua operação (uma compra paga, uma assinatura cancelada, um produto alterado), a EngagED envia um aviso para a URL do seu sistema. Aqui estão todos os eventos, o que cada um significa e o formato exato dos dados.

Antes de começar

Como ativar

Envie para suporte@engaged.com.br a URL do seu endpoint e a lista de eventos que quer receber. A ativação é feita pelo nosso time em até 48 horas.

A URL precisa ser pública e aceitar POST via HTTPS. Ferramentas como n8n e Zapier funcionam bem como receptor.

Formato do envio

Cada evento chega como um POST com corpo em JSON. O corpo é o próprio objeto do evento (a compra, a assinatura, o produto), e o campo eventType diz qual evento foi disparado.

Início de um envio de purchase.paid
POST https://seu-sistema.com.br/webhooks/engaged
Content-Type: application/json

{
"eventType": "purchase.paid",
"organization": "1962f4ab59f82366f96e7762",
"_id": "3818654df95f1a47899e28c0",
"status": "PAID",
// e os demais campos da compra: checkout, invoice, payments, user…
}

Valores monetários vêm em centavos (9990 = R$ 99,90) e datas em ISO 8601, no fuso UTC. O payload completo de cada evento, campo a campo, está na página do grupo dele.

Retentativas

Consideramos entregue quando o seu endpoint responde com status 2xx em até 15 segundos. Qualquer outra resposta gera nova tentativa, com estes intervalos contados a partir da falha anterior:

  1. na hora
  2. 5 s
  3. 5 min
  4. 30 min
  5. 2 h
  6. 5 h
  7. 10 h
  8. 10 h

Se todas as entregas para um endpoint falharem por 5 dias seguidos, ele é desativado automaticamente.

Boas práticas

Responda 200 assim que receber e processe depois, em fila. Assim uma lentidão do seu lado não vira retentativa.

O mesmo evento pode chegar mais de uma vez. Antes de agir, confira pelo _id e pelo status se aquela mudança já foi aplicada.

Eventos

Os eventos são agrupados pelo que acontece na sua operação. Cada grupo tem a sua página, com todos os eventos dele.