Webhooks
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.
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:
- na hora
- 5 s
- 5 min
- 30 min
- 2 h
- 5 h
- 10 h
- 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.
- Compras
purchase.*Ciclo de vida de uma compra no checkout: do lead capturado ao pagamento, ao reembolso e à contestação.10 eventos - Assinaturas
subscription.*Mudanças de status da assinatura como um todo: início, atraso, retomada, cancelamento e fim.5 eventos - Cobranças de assinatura
subscription.charge.*Cada cobrança recorrente de uma assinatura: gerada, paga, recusada, vencida, reembolsada ou contestada.7 eventos - Produtos
product.*Cadastro e alterações de produtos no painel.5 eventos - Matrículas
enrolment.*Marcos da matrícula do aluno em um curso, como a conclusão.1 evento