Webhooks da v2 - 4SeletPay

Os webhooks avisam a sua aplicação quando algo muda depois da resposta da API — por exemplo, quando um cartão é confirmado, um PIX é pago ou uma assinatura é renovada. A 4SeletPay envia um POST com JSON para a URL que você cadastrou.

A resposta de POST /v2/orders traz o resultado da autorização, não do pagamento. Use os webhooks para saber quando um pedido foi pago.

Cadastrar um endpoint

A API v2 não tem rota para gerenciar endpoints. Cadastre a URL e escolha os eventos no dashboard ou pela API v1:

Endpoints de Webhook (v1)

Crie, liste, atualize e remova os endpoints que recebem as notificações.

Formato v1 ou v2

O formato do webhook depende de onde o recurso foi criado, não de uma configuração do endpoint:

Recurso criado por	Formato do webhook
`POST /v2/orders` e `POST /v2/subscriptions`	v2
Rotas da API v1	v1

O mesmo endpoint pode receber os dois formatos. Use o campo webhook_version para decidir como ler o payload.

Eventos que não existem no formato v2 são entregues no formato v1, mesmo para recursos criados pela v2. É o caso de charge.challenged e dos eventos de cartão (card.*).

Envelope

{
  "id": "hook_Xy7kP2mQ9rT4vB1n",
  "type": "order.paid",
  "webhook_version": "v2",
  "created_at": "2026-09-14T15:04:05Z",
  "data": { ... }
}

Campo	Tipo	Descrição
`id`	string	Identificador da entrega (`hook_...`). Use para evitar processar a mesma notificação duas vezes
`type`	string	Evento, em notação `recurso.ação`
`webhook_version`	string	Sempre `v2` neste formato
`created_at`	string	Data e hora do evento em UTC (ISO 8601)
`data`	object	O recurso do evento (veja abaixo)

O que vem em `data`

Eventos	Conteúdo de `data`
`order.*`	O mesmo objeto de `GET /v2/orders/{id}`
`invoice.*`	O mesmo objeto de `GET /v2/invoices/{id}`
`subscription.*`	O mesmo objeto de `GET /v2/subscriptions/{id}`
`charge.*`	Um payload próprio de cobrança — veja Eventos de cobrança

Eventos disponíveis

Evento	Quando acontece
`order.paid`	Todos os pagamentos do pedido foram confirmados
`order.failed`	O pedido falhou
`order.refunded`	O pedido foi estornado
`order.chargeback`	O pedido recebeu chargeback
`charge.created`	A cobrança foi criada
`charge.pending`	A cobrança está pendente
`charge.paid`	A cobrança foi paga
`charge.failed`	A cobrança falhou
`charge.reproved`	A cobrança foi reprovada
`charge.refunded`	A cobrança foi totalmente estornada
`charge.partial_refunded`	A cobrança foi parcialmente estornada
`charge.chargeback`	A cobrança recebeu chargeback
`charge.expired`	A cobrança expirou (por exemplo, PIX não pago)
`charge.canceled`	A cobrança foi cancelada
`subscription.canceled`	A assinatura foi cancelada
`subscription.delayed`	Uma cobrança da assinatura falhou e ela ficou em atraso
`subscription.regularized`	A assinatura em atraso foi paga
`subscription.suspended`	A assinatura foi suspensa
`subscription.completed`	A assinatura pagou a última fatura prevista
`invoice.created`	Uma fatura de renovação foi gerada
`invoice.paid`	A fatura foi paga
`invoice.failed`	A cobrança da fatura falhou

Pedidos

order.paid, order.failed, order.refunded, order.chargeback

Cobranças

charge.*

Assinaturas

subscription.*

Faturas

invoice.*

Boas práticas

Responda com HTTP 2xx assim que receber a notificação. Respostas fora da faixa 2xx são reenviadas, até o limite de tentativas do endpoint.
Processe a notificação de forma assíncrona na sua aplicação, depois de responder.
Guarde o id da entrega e ignore repetições.
Não dependa da ordem de chegada dos eventos. Na dúvida, consulte o recurso pela API.

A verificação por código (OTP) não gera webhook. Ela aparece apenas no next_action da resposta do pedido ou da fatura.

​Cadastrar um endpoint

Endpoints de Webhook (v1)

​Formato v1 ou v2

​Envelope

​O que vem em data

​Eventos disponíveis

Pedidos

Cobranças

Assinaturas

Faturas

​Boas práticas

Cadastrar um endpoint

Formato v1 ou v2

Envelope

O que vem em `data`

Eventos disponíveis

Boas práticas