Esta página descreve o formato do webhook enviado pela plataforma sempre que houver uma atualização em uma recorrência ou em uma de suas cobranças.
O webhook de recorrência é enviado automaticamente sempre que o status da recorrência ou de uma cobrança for alterado, permitindo que o sistema do integrador acompanhe todo o ciclo, desde a criação até o cancelamento.
O envio vai para os webhooks do tipo Assinaturas cadastrados no painel e para a notificationUrl que você informou na criação.
Todos os campos de data e hora enviados nos webhooks utilizam o padrão ISO 8601 no timezone UTC (UTC+00:00), garantindo consistência independentemente do fuso horário do integrador. Para evitar divergências causadas por horários locais ou horário de verão, recomenda-se manter os valores em UTC para armazenamento e processamento, realizando a conversão para o fuso horário local apenas no nível de apresentação ao usuário final.
Toda notificação traz o header X-Webhook-Event, com o evento que motivou o envio. Use este header para decidir o que fazer com a notificação: o mesmo evento pode chegar com mais de um status no corpo.
Nesta página, o X-Webhook-Event pode trazer:
O recebimento é confirmado quando o seu endpoint responde com HTTP 2xx em até 30 segundos. Fora disso, a plataforma tenta de novo, até 6 tentativas no total: 1 minuto, 10 minutos, 1 hora, 6 horas e 11 horas depois da tentativa anterior.
As respostas 404, 405 e 410 encerram as tentativas na hora, porque indicam que a URL não existe ou não aceita a notificação. Como a mesma notificação pode chegar mais de uma vez, processe o recebimento de forma idempotente.
Para aumentar a segurança, os webhooks cadastrados diretamente no painel podem incluir uma assinatura enviada no header X-Signature: <assinatura-em-base64>, permitindo validar a autenticidade da notificação recebida. Essa assinatura é gerada pela plataforma utilizando HMAC com SHA-256 sobre o corpo do webhook, em formato JSON, usando um segredo compartilhado WEBHOOK_SECRET e codificada em Base64. O integrador pode reproduzir o mesmo cálculo em seu sistema utilizando o mesmo segredo e o payload recebido. Se a assinatura gerada for igual à enviada no header, o webhook é considerado legítimo e íntegro. Caso sejam diferentes, a requisição pode ter sido alterada ou não ter sido enviada pela plataforma.
Essa validação está disponível apenas para webhooks cadastrados no painel. Webhooks enviados para uma URL informada dinamicamente via notificationUrl não incluem a assinatura X-Signature.
A validação por assinatura é opcional, porém fortemente recomendada sempre que o webhook for configurado pelo painel, para garantir maior segurança na comunicação.
Caso informado, o webhook será enviado para a URL configurada no campo notificationUrl no momento da criação da recorrência.
O endpoint deve estar acessível publicamente e responder com HTTP 200 para confirmar o recebimento da notificação.
Além disso, as notificações de recorrência também podem ocorrer via webhook in-bound, cadastrado no painel com o tipo Assinaturas. Webhook cadastrado como Pagamentos não recebe evento de recorrência.
Os possíveis valores para o campo status são:
Os possíveis valores para o campo invoice.status são:
O evento vem no header <strong>X-Webhook-Event</strong>; o corpo não tem campo de evento. Quando o campo invoice vem nulo, o aviso é sobre a recorrência. Quando vem preenchido, é sobre uma cobrança.
O status da recorrência é consequência das cobranças:
A cobrança chega como | A recorrência fica |
|---|---|
| SCHEDULED | Sem mudança |
| PAID (a primeira) | ACTIVE |
| PAID (as seguintes) | Continua ACTIVE |
| REJECTED | CANCELLED |
A recorrência também é cancelada sem passar por cobrança nenhuma: quando o pagador recusa a autorização, quando você chama a rota de cancelamento, quando o contrato é cancelado ou pausado fora da plataforma e quando o ciclo fica 15 dias vencido sem pagamento (cancelamento automático). Nos quatro casos o aviso chega com invoice nulo, e a cobrança que estava agendada é encerrada junto, sem aviso próprio.
O mesmo aviso pode chegar mais de uma vez, e o agendamento e o pagamento de um ciclo compartilham o mesmo invoice.id. Para não processar duas vezes, use id + status + invoice.id + invoice.status.
O corpo é o mesmo em todos os eventos. O que muda são os campos status e invoice.
{
"id": "cm6r0k3j20001ls08d5f7h9kb",
"amount": 9900,
"currency": "BRL",
"method": "PIXAUTOMATIC",
"status": "ACTIVE",
"description": "Assinatura mensal",
"discount": null,
"options": {
"frequency": "MONTHLY",
"freqInterval": 1,
"maxPeriods": null
},
"customer": {
"name": "John Doe",
"taxId": "12345678909",
"email": "john.doe@example.com",
"phone": "+5511999990000"
},
"pix": {
"emv": "00020101021226850014br.gov.bcb.pix2563api.gateway.test/pix/123e4567-e89b-12d3-a456-4266141740005204000053039865802BR6304ABCD",
"retryPolicy": "THREE_RETRIES_7_DAYS"
},
"card": null,
"invoice": {
"id": "cm6r1m4n50003ls08g8j2k5lc",
"amount": 9900,
"status": "PAID",
"e2e": "E1234567890123456789012345678901",
"refusedMsg": null,
"periodNumber": 1,
"periodStart": "2026-01-05",
"periodEnd": "2026-02-05",
"paidAt": "2026-01-05T10:15:10.000Z",
"cancelledAt": null,
"lastTryAt": "2026-01-05T10:15:08.000Z",
"createdAt": "2026-01-05T10:12:33.120Z",
"updatedAt": "2026-01-05T10:15:10.000Z"
},
"orderId": null,
"cancelledAt": null,
"externalRef": "order_123456",
"notificationUrl": "https://example.com/webhook/recurrency",
"metadata": null,
"createdAt": "2026-01-05T10:12:33.120Z",
"updatedAt": "2026-01-05T10:15:10.000Z"
}