Skip to content
A AmunPay API PixVersion 3.38 · updated on Pages

Webhooks

You register an HTTPS URL and receive a POST for each event. Delivery is signed, tries 9 times over about 5 hours, and each address has its own queue: a slow endpoint of yours does not delay anyone else.

Register #

PUT /v2/ex/webhook

Scope: ex.webhook.write.

PUT /v2/ex/webhook
{
  "url": "https://loja.exemplo.com/webhooks/pix",
  "tiposHabilitados": ["*"],
  "urlsPorFamilia": {
    "payout": "https://loja.exemplo.com/webhooks/saques"
  }
}
→ 200
{
  "url": "https://loja.exemplo.com/webhooks/pix",
  "tiposHabilitados": ["*"],
  "urlsPorFamilia": {
    "payout": "https://loja.exemplo.com/webhooks/saques"
  },
  "ativo": true,
  "atualizadoEm": "2026-09-18T12:00:00Z"
}
Field Type Required Description
url string yes Public HTTPS. Receives everything that has no redirect.
tiposHabilitados list no ["*"] for all, or the types you want. If absent, ["*"] applies.
urlsPorFamilia object no Redirect by family. The family is the first segment of the type, and GET /v2/ex/webhook/familias lists the accepted ones.
cabecalhos object no Up to 3 headers of yours on every delivery. The value does not come back when reading.

The PUT describes the final state: omitting urlsPorFamilia deletes the redirects. A field the route does not know responds 400 campo_desconhecido. GET /v2/ex/webhook reads the configuration, DELETE /v2/ex/webhook turns delivery off and GET /v2/ex/webhook/familias lists the accepted families.

The envelope #

Every event arrives with this body. Respond 2xx within 10 seconds and process it afterwards. Respond 2xx to a type you do not know as well.

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N002",
  "tipo": "pix.creditado",
  "criadoEm": "2026-10-23T15:00:07.412Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "endToEndId": "E60746948202610231500Ab1Cd2Ef3Gh",
    "txid": "FIN02J1ZK7M9QW3ERT5TY6UI8O",
    "valor": "150.00",
    "situacaoFundos": "CREDITADO",
    "pagador": { "cpf": "12345678909", "nome": "Fulano de Tal", "ispb": "60746948" },
    "titularidadeOk": true,
    "instrumento": "PIX",
    "horario": { "liquidacao": "2026-10-23T15:00:07.001Z" }
  }
}
Field Type Description
eventoId string Unique. Discard repeats by it: delivery is at least once.
sequencia integer Grows per resource (txid, idEnvio). The order between different resources is not guaranteed.
correlationId string The id of the request that originated the event. It may be absent, as in the payout deadline events.
dados object The content of the event. The keys vary by type. In pagador, a company comes in cnpj instead of cpf. When the payment institution only reports the payer document masked, it comes as the institution sent it in cpfMascarado (or cnpjMascarado), with cpf empty.

Your response #

Respond 2xx as soon as you receive it. An event you reject, or on which your system fails, is retried on its own and does not stop the others. The queue of the address only pauses when the endpoint seems to be down.

Your address receives several events at the same time, from different resources. The number adjusts by itself: it starts at 8 and rises while the address answers 2xx quickly, up to 512, and falls when it fails or is slow. Events of the same resource arrive one at a time, in the order of sequencia. An address that has not answered 2xx yet, or that failed after the last 2xx, receives one at a time. The rejection of an event does not count.

Response What happens
2xx Delivered.
400, 409, 413 or 422 Rejection of this event. It retries on its own and the others keep arriving. The ones for the same resource wait behind it.
5xx, or no response within 10 seconds with the connection open Failure of this event. It retries on its own and the others keep arriving. The ones for the same resource wait behind it.
A connection that does not open (DNS, TLS, connection refused), 401, 403, 404, 405, 410 or any other response The address is down. The events that failed wait, and one of them tests the address until it comes back. A new event is tried anyway.

With 3 different events failing on the same address, none with a 2xx from it since the first failure, the address also pauses. No event holds back another: there is no limit on rejected events, and a new event goes out even with the address paused. When an event arrives with 2xx at a paused address, delivery to it resumes immediately, and an event that failed before that 2xx, including with 404, starts retrying on its own without pausing the address.

The signature #

Each delivery carries the header x-jws-signature with a detached ES256 JWS over the body. The public key is at GET /.well-known/jwks.json. Verify it before trusting the body.

Your own headers #

If a firewall or gateway in front of your endpoint requires a token, register up to 3 headers. They go on every delivery, to the general URL and to the redirects.

PUT /v2/ex/webhook
{
  "url": "https://loja.exemplo.com/webhooks/pix",
  "tiposHabilitados": ["*"],
  "cabecalhos": {
    "Authorization": "Bearer token-do-seu-gateway"
  }
}
→ 200
{
  "url": "https://loja.exemplo.com/webhooks/pix",
  "tiposHabilitados": ["*"],
  "cabecalhos": {
    "Authorization": null
  },
  "ativo": true,
  "atualizadoEm": "2026-09-29T12:00:00Z"
}

Omitting cabecalhos keeps the stored ones, {} deletes all of them, a name with null keeps that value and a stored name that does not come in the object is deleted. Changing the url does not delete the headers. The signature remains mandatory: the headers go along with it, never in its place.

Events #

Type When
pix.recebido The Pix settled. It is not balance yet. With situacaoFundos EM_DEVOLUCAO, it was rejected and goes back to the payer.
pix.creditado The money became balance. Credit your customer here.
pix.retido The Pix came in and was put on hold.
cob.pagamento_rejeitado We rejected the payment. motivo says why. If custodia.recusaAntesDoCredito is false in GET /v2/ex/config, the money came in and goes back to the payer: pix.recebido with EM_DEVOLUCAO and devolucao.criada follow.
cob.atualizada The charge was changed or cancelled.
devolucao.criada A refund went out, yours or ours. motivo says which.
devolucao.concluida The refund settled.
devolucao.nao_realizada The refund did not go out. In the one you requested, the bank of the payer rejected it. In ours, the Pix did not go back to the payer and was credited to you: pix.creditado arrives separately, with no guaranteed order between the two.
payout.aguardando_aprovacao The payout stopped at an approval rule, or you asked for approval, and is waiting for a manager in the dashboard. The amount has already left the available balance. Without endToEndId.
payout.em_processamento The payout is being sent. Without approval, the amount leaves the available balance now.
payout.realizado The payout settled. endToEndId is the final one. Carries recebedor when the institution reports who received it.
payout.nao_realizado The payout was rejected. The amount went back to the available balance.
payout.devolucao_recebida The bank of the payee returned a payout already completed.
payout.sla.em_risco 30 minutes are left until the deadline of the payout.
payout.sla.estourado The deadline of the payout passed with it still in progress.
favorecido.criado Someone registered a destination for payouts in the dashboard. It is already valid: liberaEm is the registration itself. If you do not recognize it, remove it.
favorecido.liberado The institution released, before the deadline, a destination that was waiting. It already receives, and liberaEm says since when. If you do not recognize it, remove it.
favorecido.renomeado The institution corrected, at your request, the name of a destination. Only the name changes: the key, the document and the waiting period stay as they were.
favorecido.removido The destination left the list.
med.infracao.criada A received Pix was disputed. See Disputes.
med.infracao.atualizada The dispute changed status or reached an outcome.
saldo.bloqueado Part of the balance was put on hold.
saldo.desbloqueado The hold ended.
subconta.atualizada A sub-account was created, changed status or had its custodiante changed. statusAnterior only comes on a status change.
conta.status_alterado Your account changed status.
conta.segmento_alterado The institution reclassified your account. Read GET /v2/ex/config again.
conta.custodiante_alterado Your main account now lives at another institution. custodiante and custodianteAnterior carry the name of each one. Read GET /v2/ex/config again.
split.executado A receipt was split.
split.revertido A refund or a dispute undid the split.
tarifa.cobrada A fee was charged. On an incoming payment, meio is PIX_RECEBIDO and referencia is the txid; on a completed payout, meio is PIX_ENVIADO and referencia is the idEnvio. valor is the fee.
webhook.teste Triggered by POST /v2/ex/webhook/teste. When it arrives, the paused delivery of that address starts trying again.

Examples of each event #

The whole body your endpoint receives for each type, with fictitious values. A new key may appear in dados: ignore the ones you do not know.

pix.recebido #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N001",
  "tipo": "pix.recebido",
  "criadoEm": "2026-10-23T15:00:07.212Z",
  "sequencia": 1,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "endToEndId": "E60746948202610231500Ab1Cd2Ef3Gh",
    "txid": "FIN02J1ZK7M9QW3ERT5TY6UI8O",
    "valor": "150.00",
    "situacaoFundos": "RECEBIDO",
    "pagador": { "cpf": "12345678909", "nome": "Fulano de Tal", "ispb": "60746948" },
    "instrumento": "PIX",
    "horario": { "liquidacao": "2026-10-23T15:00:07.001Z" }
  }
}

pix.creditado #

On a payment with a split, split comes too, and on a sub-account, subconta.

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N002",
  "tipo": "pix.creditado",
  "criadoEm": "2026-10-23T15:00:07.412Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "endToEndId": "E60746948202610231500Ab1Cd2Ef3Gh",
    "txid": "FIN02J1ZK7M9QW3ERT5TY6UI8O",
    "valor": "150.00",
    "situacaoFundos": "CREDITADO",
    "pagador": { "cpf": "12345678909", "nome": "Fulano de Tal", "ispb": "60746948" },
    "titularidadeOk": true,
    "instrumento": "PIX",
    "horario": { "liquidacao": "2026-10-23T15:00:07.001Z" }
  }
}

pix.retido #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N003",
  "tipo": "pix.retido",
  "criadoEm": "2026-10-23T18:20:41.090Z",
  "sequencia": 4,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "endToEndId": "E60746948202610231500Ab1Cd2Ef3Gh",
    "valor": "100.00",
    "situacaoFundos": "RETIDO",
    "tipo": "MED",
    "bloqueio": { "id": "med:01JB2Q7M9QW3ERT5TY6VK8NPQR", "tipo": "MED" }
  }
}

cob.pagamento_rejeitado #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N004",
  "tipo": "cob.pagamento_rejeitado",
  "criadoEm": "2026-10-23T15:10:02.530Z",
  "sequencia": 1,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "txid": "FIN03JB2Q7M9QW3ERT5TY6VK8N",
    "motivo": "TITULARIDADE",
    "politica": "RECUSAR",
    "pagador": { "cpf": "98765432100" },
    "cpfMascaradoPagador": "***654321**"
  }
}

cob.atualizada #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N005",
  "tipo": "cob.atualizada",
  "criadoEm": "2026-10-23T15:12:30.118Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "txid": "FIN04JB2Q7M9QW3ERT5TY6VK8N",
    "revisao": 1,
    "status": "ATIVA",
    "valor": "120.00",
    "pixCopiaECola": "00020126480014br.gov.bcb.pix0126...6304C057"
  }
}

devolucao.criada #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N006",
  "tipo": "devolucao.criada",
  "criadoEm": "2026-10-23T16:00:00.401Z",
  "sequencia": 1,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "endToEndId": "E60746948202610231500Ab1Cd2Ef3Gh",
    "txid": "FIN02J1ZK7M9QW3ERT5TY6UI8O",
    "id": "D1",
    "valor": "10.00",
    "motivo": "SOLICITADA",
    "natureza": "ORIGINAL"
  }
}

devolucao.concluida #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N007",
  "tipo": "devolucao.concluida",
  "criadoEm": "2026-10-23T16:00:02.877Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "endToEndId": "E60746948202610231500Ab1Cd2Ef3Gh",
    "id": "D1",
    "rtrId": "D12345678202610231600Mn4Pq7Rs2Tv",
    "valor": "10.00"
  }
}

devolucao.nao_realizada #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N008",
  "tipo": "devolucao.nao_realizada",
  "criadoEm": "2026-10-23T16:05:01.954Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "endToEndId": "E60746948202610231500Ab1Cd2Ef3Gh",
    "id": "D2",
    "motivo": "AC06"
  }
}

payout.aguardando_aprovacao #

regras says which rules stopped the payout: PEDIDA, VALOR, QUANTIDADE_DESTINO or SOMA_DESTINO.

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N009",
  "tipo": "payout.aguardando_aprovacao",
  "criadoEm": "2026-10-23T15:20:00.330Z",
  "sequencia": 1,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "idEnvio": "SAQ02JB2Q7M9QW3ERT5TY6VK8N",
    "valor": "7500.00",
    "tipo": "SAQUE",
    "origem": "API",
    "regras": ["VALOR"],
    "expiraEm": "2026-10-24T15:20:00Z"
  }
}

payout.em_processamento #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N010",
  "tipo": "payout.em_processamento",
  "criadoEm": "2026-10-23T15:30:00.215Z",
  "sequencia": 1,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "idEnvio": "SAQ01JB2Q7M9QW3ERT5TY6VK8N",
    "endToEndId": "E12345678202610231530Kd7Fp2Rt9Wx",
    "valor": "20.00",
    "tipo": "SAQUE",
    "origem": "API",
    "prazoRegulatorio": "2026-10-23T17:30:00Z"
  }
}

payout.realizado #

recebedor only comes when the institution reports who received it.

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N011",
  "tipo": "payout.realizado",
  "criadoEm": "2026-10-23T15:30:03.640Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "idEnvio": "SAQ01JB2Q7M9QW3ERT5TY6VK8N",
    "endToEndId": "E12345678202610231530Kd7Fp2Rt9Wx",
    "valor": "20.00",
    "tipo": "SAQUE",
    "origem": "API",
    "sla": { "cumprido": true },
    "recebedor": {
      "nome": "Fulano de Tal",
      "documento": "12345678909",
      "ispb": "18236120",
      "banco": "NU PAGAMENTOS - IP",
      "bancoNomeCompleto": "NU PAGAMENTOS S.A. - INSTITUIÇÃO DE PAGAMENTO",
      "bancoCodigo": "260",
      "bancoCnpj": "18236120000158",
      "agencia": "0001",
      "conta": "35",
      "tipoConta": "TRAN"
    }
  }
}

payout.nao_realizado #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N012",
  "tipo": "payout.nao_realizado",
  "criadoEm": "2026-10-23T15:35:01.102Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "idEnvio": "SAQ03JB2Q7M9QW3ERT5TY6VK8N",
    "tipo": "SAQUE",
    "origem": "API",
    "motivo": {
      "codigo": "AC03",
      "classe": "CORRIGIVEL",
      "descricao": "Agência/conta do usuário recebedor inexistente ou inválida."
    }
  }
}

payout.devolucao_recebida #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N013",
  "tipo": "payout.devolucao_recebida",
  "criadoEm": "2026-10-23T17:02:44.510Z",
  "sequencia": 3,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "idEnvio": "SAQ01JB2Q7M9QW3ERT5TY6VK8N",
    "endToEndIdOriginal": "E12345678202610231530Kd7Fp2Rt9Wx",
    "rtrId": "D18236120202610231702Hj5Kl8Mn1Pq",
    "valor": "20.00",
    "natureza": "ORIGINAL",
    "motivo": "Devolvido pela instituição de quem recebeu.",
    "devolvidaEm": "2026-10-23T17:01:58Z"
  }
}

payout.sla.em_risco #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N014",
  "tipo": "payout.sla.em_risco",
  "criadoEm": "2026-10-23T17:00:00.019Z",
  "sequencia": 2,
  "dados": {
    "idEnvio": "SAQ04JB2Q7M9QW3ERT5TY6VK8N",
    "tipo": "SAQUE",
    "valor": "300.00",
    "status": "EM_PROCESSAMENTO",
    "prazoRegulatorio": "2026-10-23T17:30:00Z",
    "sla": { "estourado": false, "restanteSegundos": 1800 }
  }
}

payout.sla.estourado #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N015",
  "tipo": "payout.sla.estourado",
  "criadoEm": "2026-10-23T17:31:00.024Z",
  "sequencia": 3,
  "dados": {
    "idEnvio": "SAQ04JB2Q7M9QW3ERT5TY6VK8N",
    "tipo": "SAQUE",
    "valor": "300.00",
    "status": "EM_PROCESSAMENTO",
    "prazoRegulatorio": "2026-10-23T17:30:00Z",
    "sla": { "estourado": true, "restanteSegundos": -60 }
  }
}

favorecido.criado #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N016",
  "tipo": "favorecido.criado",
  "criadoEm": "2026-10-23T14:00:00.711Z",
  "sequencia": 1,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "id": "01JB2Q3F8ZX6M7MMJ99YRB5AYG",
    "chave": "financeiro@fornecedor.com.br",
    "tipoChave": "EMAIL",
    "nome": "Fornecedor Exemplo Ltda",
    "criadoPor": "joao.silva",
    "liberaEm": "2026-10-23T14:00:00Z"
  }
}

favorecido.liberado #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N017",
  "tipo": "favorecido.liberado",
  "criadoEm": "2026-10-23T14:10:00.302Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "id": "01JB2Q3F8ZX6M7MMJ99YRB5AYG",
    "chave": "financeiro@fornecedor.com.br",
    "nome": "Fornecedor Exemplo Ltda",
    "liberaEm": "2026-10-23T14:10:00Z",
    "liberavaEm": "2026-10-24T14:00:00Z"
  }
}

favorecido.renomeado #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N018",
  "tipo": "favorecido.renomeado",
  "criadoEm": "2026-10-23T14:20:00.845Z",
  "sequencia": 3,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "id": "01JB2Q3F8ZX6M7MMJ99YRB5AYG",
    "chave": "financeiro@fornecedor.com.br",
    "nome": "Fornecedor Exemplo Comércio Ltda",
    "nomeAnterior": "Fornecedor Exemplo Ltda",
    "renomeadoPor": "instituicao"
  }
}

favorecido.removido #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N019",
  "tipo": "favorecido.removido",
  "criadoEm": "2026-10-23T14:30:00.127Z",
  "sequencia": 4,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "id": "01JB2Q3F8ZX6M7MMJ99YRB5AYG",
    "chave": "financeiro@fornecedor.com.br",
    "motivo": "trocou de banco",
    "removidoPor": "joao.silva"
  }
}

med.infracao.criada #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N020",
  "tipo": "med.infracao.criada",
  "criadoEm": "2026-10-23T18:20:41.090Z",
  "sequencia": 1,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "idInfracao": "01JB2Q7M9QW3ERT5TY6VK8NPQR",
    "endToEndId": "E60746948202610231500Ab1Cd2Ef3Gh",
    "tipo": "FRAUDE",
    "valor": "100.00",
    "situacao": "ABERTA",
    "prazoFinalizacao": "2026-10-30T18:20:41Z"
  }
}

med.infracao.atualizada #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N021",
  "tipo": "med.infracao.atualizada",
  "criadoEm": "2026-10-28T12:00:00.640Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "idInfracao": "01JB2Q7M9QW3ERT5TY6VK8NPQR",
    "situacao": "REJEITADA",
    "encerradaPor": "MED"
  }
}

saldo.bloqueado #

On a hold that is not from a dispute, such as a court order, only id, tipo and valor come.

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N022",
  "tipo": "saldo.bloqueado",
  "criadoEm": "2026-10-23T18:20:41.090Z",
  "sequencia": 1,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "id": "med:01JB2Q7M9QW3ERT5TY6VK8NPQR",
    "tipo": "MED",
    "valor": "100.00",
    "endToEndId": "E60746948202610231500Ab1Cd2Ef3Gh",
    "idInfracao": "01JB2Q7M9QW3ERT5TY6VK8NPQR",
    "prazo": "2026-10-30T18:20:41Z"
  }
}

saldo.desbloqueado #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N023",
  "tipo": "saldo.desbloqueado",
  "criadoEm": "2026-10-28T12:00:00.640Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "id": "med:01JB2Q7M9QW3ERT5TY6VK8NPQR",
    "tipo": "MED",
    "valor": "100.00",
    "endToEndId": "E60746948202610231500Ab1Cd2Ef3Gh",
    "desfecho": "LIBERADO"
  }
}

subconta.atualizada #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N024",
  "tipo": "subconta.atualizada",
  "criadoEm": "2026-10-23T13:00:00.411Z",
  "sequencia": 1,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "id": "SUB01JB2Q7M9QW3ERT5TY6VK8N",
    "nome": "Filial Centro",
    "cnpj": "11222333000181",
    "status": "EM_ANALISE"
  }
}

conta.status_alterado #

efeitos says what was taken out of circulation by the block.

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N025",
  "tipo": "conta.status_alterado",
  "criadoEm": "2026-10-23T19:00:00.072Z",
  "sequencia": 1,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "status": "BLOQUEADA",
    "statusAnterior": "ATIVA",
    "motivo": "COMPLIANCE",
    "efeitos": [{ "acao": "COBS_REMOVIDAS", "quantidade": 2 }]
  }
}

conta.custodiante_alterado #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N026",
  "tipo": "conta.custodiante_alterado",
  "criadoEm": "2026-10-23T19:30:00.588Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "custodiante": "Conta nominal B",
    "custodianteAnterior": "Conta nominal A"
  }
}

split.executado #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N027",
  "tipo": "split.executado",
  "criadoEm": "2026-10-23T15:40:05.330Z",
  "sequencia": 4,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "txid": "FIN05JB2Q7M9QW3ERT5TY6VK8N",
    "endToEndId": "E60746948202610231540Qw3Er5Ty7Ui",
    "referencia": "FIN05JB2Q7M9QW3ERT5TY6VK8N",
    "meio": "PIX",
    "config": "afiliados",
    "valorTotal": "99.60",
    "repartido": "9.96",
    "retidoRecebedor": "89.64",
    "pernas": [{ "parceiro": "afiliado-01", "bps": 1000, "valor": "9.96" }]
  }
}

split.revertido #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N028",
  "tipo": "split.revertido",
  "criadoEm": "2026-10-23T16:10:00.902Z",
  "sequencia": 5,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "referencia": "FIN05JB2Q7M9QW3ERT5TY6VK8N",
    "meio": "PIX",
    "valorRevertido": "50.00",
    "recuperado": "5.00",
    "descoberto": "0.00",
    "pernas": [{ "parceiro": "afiliado-01", "revertido": "5.00", "descoberto": "0.00" }]
  }
}

tarifa.cobrada #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N029",
  "tipo": "tarifa.cobrada",
  "criadoEm": "2026-10-23T15:00:07.413Z",
  "sequencia": 3,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "meio": "PIX_RECEBIDO",
    "referencia": "FIN02J1ZK7M9QW3ERT5TY6UI8O",
    "valor": "0.40",
    "valorBase": "150.00",
    "faixa": 0
  }
}

webhook.teste #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N030",
  "tipo": "webhook.teste",
  "criadoEm": "2026-10-23T12:00:00.000Z",
  "sequencia": 1,
  "dados": {
    "mensagem": "entrega de teste do webhookd"
  }
}

Queue health #

GET /v2/ex/webhook/saude

Scope: ex.webhook.read.

GET /v2/ex/webhook/saude
→ 200
{
  "situacao": "OK",
  "entregues": 0,
  "emBackoff": 0,
  "recusadas": 0,
  "comErro": 0,
  "desistidas": 0,
  "janelaHoras": 24
}

situacao is OK, ATENCAO or FALHANDO. Outside OK, motivo comes along; with FALHANDO, ultimaFalha also comes, with falha RECUSA, ERRO or INDISPONIBILIDADE. recusadas counts the ones your endpoint rejected and comErro the ones on which it failed, and both keep retrying. Abandoned deliveries are no longer sent on their own: fix the endpoint and request a resend.

Resend #

POST /v2/ex/webhook/reenvios

Scope: ex.webhook.write.

POST /v2/ex/webhook/reenvios
{
  "tipos": ["pix.creditado"],
  "inicio": "2026-09-17T12:00:00Z",
  "fim": "2026-09-18T12:00:00Z",
  "dryRun": true
}
→ 202
{
  "idReenvio": "01M2SX3Q56B91Y7HDH49X0QQH5",
  "status": "CONCLUIDO",
  "total": 0,
  "enfileirados": 0,
  "dryRun": true
}

dryRun: true only counts. soFalhas: true resends only the callbacks that failed: those that used up their attempts without your endpoint accepting them and were never delivered. The window reaches up to 30 days back and inicio cannot be in the future; a fim in the future counts as now. Without an active webhook, the resend ends INTERROMPIDO. GET /v2/ex/webhook/reenvios/{id} follows a resend, GET /v2/ex/webhook/reenvios lists the 10 most recent, POST /v2/ex/webhook/reenvios/{id}/cancelar cancels a resend while any of its callbacks has not gone out, also one that has already finished putting its callbacks in the queue (CONCLUIDO): it becomes INTERROMPIDO, and its callbacks that have not gone out yet are not sent, counted in naoEnviados, GET /v2/ex/webhook/entregas lists the attempts with HTTP status and latency, filters by status (PENDENTE, ENTREGUE or FALHA_PERMANENTE) and continues by ?cursor=, and GET /v2/ex/eventos is the feed of the same envelopes, for reconciliation: it advances by ?apos= with the cursor.proximo of the previous page. To see what happened just now first, use ?ordem=recentes, which advances by ?antes=.

Errors #

Status title When
400 url_invalida The URL is not valid HTTPS.
400 url_privada The URL points to a private network or localhost, or the host does not resolve in DNS.
400 familia_desconhecida urlsPorFamilia mentions a family that does not exist.
400 tipos_invalidos A blank item in tiposHabilitados.
400 cabecalho_invalido Name or value outside the format, the same name twice with different case, more than 3, or null for a name with no stored value.
400 cabecalho_proibido A connection header, a body header or one of ours, such as Host, Content-Type or x-jws-signature.
400 campo_desconhecido A field the route does not know, such as headers instead of cabecalhos.
400 periodo_invalido inicio or fim of the resend outside RFC 3339.
400 janela_invalida fim is not after inicio, or inicio is in the future.
400 janela_muito_antiga inicio is more than 30 days old.
404 nao_encontrado GET or DELETE with no webhook registered, or a resend that does not exist.
409 reenvio_em_andamento There is already a resend in progress.
409 reenvio_encerrado The resend you want to cancel has already finished, and all of its callbacks have already gone out.
422 webhook_nao_configurado Test without an active webhook.
503 cabecalhos_indisponiveis The installation cannot store headers right now. Nothing was stored.