Visão geral
Formato da requisição
Todas as requisições de webhook são enviadas com:
- Método:
POST - Content-Type:
application/json - Corpo: um objeto JSON com a estrutura abaixo
Estrutura do payload
Cada requisição enviada para sua URL tem o seguinte formato:
{
"event": "nome.do.evento",
"data": { ... },
"timestamp": "2025-01-28T12:00:00.000Z",
"webhookId": "uuid-do-webhook"
}
| Campo | Tipo | Descrição |
|---|---|---|
event | string | Nome do evento (ex.: purchase.approved, pix.generated). |
data | object | Dados específicos do evento (transação, assinatura, cliente, etc.). |
timestamp | string | Data/hora do disparo em ISO 8601. |
webhookId | string | ID do webhook no TukanoPay (útil para logs). |
Headers enviados
| Header | Descrição |
|---|---|
Content-Type | application/json |
X-Webhook-Event | Nome do evento (mesmo valor de event no body). |
X-Webhook-Id | ID do webhook. |
X-Webhook-Signature | Assinatura HMAC SHA256 do body (apenas se você configurou um secret no webhook). Use para validar a autenticidade. |
Lista de eventos
| Evento | Descrição |
|---|---|
purchase.approved | Compra aprovada (cartão ou PIX confirmado). |
purchase.refused | Compra recusada (todas as tentativas de pagamento falharam). |
pix.generated | QR Code PIX gerado (pagamento pendente). |
refund | Reembolso processado. |
chargeback | Chargeback registrado pela adquirente. |
subscription.renewed | Assinatura criada ou renovada. |
subscription.cancelled | Assinatura cancelada. |
subscription.delayed | Assinatura atrasada/suspensa (falhas de cobrança). |
cart.abandoned | Carrinho abandonado (checkout não finalizado). |
Nos próximos tópicos você encontra o payload completo de cada evento.
Rastreamento (UTM e afins)
Se o checkout receber os parâmetros de rastreamento abaixo (query string ou body), eles são salvos na transação/assinatura e sempre enviados nos webhooks no objeto data.tracking:
| Parâmetro | Descrição (uso típico) |
|---|---|
utm_source | Origem (ex.: google, newsletter). |
utm_campaign | Campanha (ex.: blackfriday). |
utm_medium | Meio (ex.: cpc, email). |
utm_content | Conteúdo (ex.: banner-1). |
cid | ID de campanha (ex.: clique em anúncio). |
src | Fonte (ex.: rede social). |
Assim, produtores podem rastrear vendas por campanha, anúncio ou origem. O objeto tracking em cada evento contém apenas as chaves que foram enviadas no checkout (objeto vazio {} se nenhum parâmetro foi passado).