Webhook de recorrência

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.

Descrição

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.

Padrão de Timezone

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.

Validação Opcional do Webhook

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.

Endpoint de Notificaçã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.

Status da recorrência

Os possíveis valores para o campo status são:

• PENDING – Recorrência criada, aguardando a autorização do pagador ou a primeira cobrança.
• ACTIVE – Primeira cobrança paga. No cartão ela pode acontecer já na criação; no Pix Automático, no primeiro ciclo.
• CANCELLED – Recorrência encerrada. Nenhuma cobrança nova é gerada.
• FAILED – A adquirente recusou o cartão na criação. A recorrência não chega a existir para ela.

Status da cobrança

Os possíveis valores para o campo invoice.status são:

• SCHEDULED – Cobrança agendada para o ciclo, ainda não cobrada.
• PAID – Cobrança paga. O valor entra no seu saldo.
• REJECTED – Cobrança recusada em definitivo. A recorrência é cancelada junto.

Como os dois se relacionam

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:

To pick up a draggable item, press the space bar. While dragging, use the arrow keys to move the item. Press space again to drop the item in its new position, or press escape to cancel.

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 e quando o contrato é cancelado ou pausado no painel da adquirente. Nos três 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.

Formato do payload

O corpo é o mesmo em todos os eventos. O que muda são os campos status e invoice.

{
  "id": "recr_01HXYZ123ABC456DEF789",
  "amount": 9900,
  "currency": "BRL",
  "method": "PIXAUTOMATIC",
  "status": "ACTIVE",
  "description": "Assinatura mensal",
  "options": {
    "frequency": "MONTHLY",
    "freqInterval": 1,
    "maxPeriods": null
  },
  "customer": {
    "name": "John Doe",
    "taxId": "12345678900",
    "email": "john.doe@example.com",
    "phone": "11999990000"
  },
  "pix": {
    "emv": "00020101021226850014br.gov.bcb.pix2563api.gateway.test/pix/123e4567-e89b-12d3-a456-4266141740005204000053039865802BR6304ABCD",
    "retryPolicy": "THREE_RETRIES_7_DAYS"
  },
  "card": null,
  "invoice": {
    "id": "rinv_01HXYZ987ZYX654",
    "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"
}

{
  "id": "recr_01HXYZ123ABC456DEF789",
  "amount": 4990,
  "currency": "BRL",
  "method": "CREDIT_CARD",
  "status": "CANCELLED",
  "description": "Assinatura mensal",
  "options": {
    "frequency": "MONTHLY",
    "freqInterval": 1,
    "maxPeriods": null
  },
  "customer": {
    "name": "John Doe",
    "taxId": "12345678900",
    "email": "john.doe@example.com",
    "phone": "11999990000"
  },
  "pix": null,
  "card": {
    "brand": "VISA",
    "holder": "JOHN DOE",
    "number": "411111******1111",
    "refusedMsg": null
  },
  "invoice": {
    "id": "rinv_01HXYZ987ZYX654",
    "amount": 4990,
    "status": "REJECTED",
    "e2e": null,
    "refusedMsg": "Cartão sem limite disponível.",
    "periodNumber": 4,
    "periodStart": "2026-04-05",
    "periodEnd": "2026-05-05",
    "paidAt": null,
    "cancelledAt": "2026-04-12T18:45:10.532Z",
    "lastTryAt": "2026-04-12T18:45:10.000Z",
    "createdAt": "2026-01-05T10:12:33.120Z",
    "updatedAt": "2026-04-12T18:45:10.532Z"
  },
  "orderId": null,
  "cancelledAt": "2026-04-12T18:45:10.532Z",
  "externalRef": "order_123456",
  "notificationUrl": "https://example.com/webhook/recurrency",
  "metadata": null,
  "createdAt": "2026-01-05T10:12:33.120Z",
  "updatedAt": "2026-04-12T18:45:10.532Z"
}