Ir para o conteúdo
A AmunPay API PixVersão 3.38 · atualizada em Páginas

Webhooks

Você cadastra uma URL HTTPS e recebe um POST a cada evento. A entrega é assinada, tenta 9 vezes em cerca de 5 horas, e cada endereço tem a sua fila: um endpoint lento seu não atrasa ninguém.

Cadastrar #

PUT /v2/ex/webhook

Escopo: 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"
}
Campo Tipo Obrigatório Descrição
url string sim HTTPS público. Recebe tudo que não tem desvio.
tiposHabilitados lista não ["*"] para todos, ou os tipos que você quer. Ausente vale ["*"].
urlsPorFamilia objeto não Desvio por família. A família é o primeiro segmento do tipo, e GET /v2/ex/webhook/familias lista as aceitas.
cabecalhos objeto não Até 3 cabeçalhos seus em toda entrega. O valor não volta na leitura.

O PUT descreve o estado final: omitir urlsPorFamilia apaga os desvios. Um campo que a rota não conhece responde 400 campo_desconhecido. GET /v2/ex/webhook lê a configuração, DELETE /v2/ex/webhook desativa a entrega e GET /v2/ex/webhook/familias lista as famílias aceitas.

O envelope #

Todo evento chega com este corpo. Responda 2xx em até 10 segundos e processe depois. Responda 2xx também a um tipo que você não conhece.

{
  "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" }
  }
}
Campo Tipo Descrição
eventoId string Único. Descarte repetidos por ele: a entrega é ao menos uma vez.
sequencia inteiro Cresce por recurso (txid, idEnvio). A ordem entre recursos diferentes não é garantida.
correlationId string O id da requisição que originou o evento. Pode não vir, como nos avisos do prazo do saque.
dados objeto O conteúdo do evento. As chaves variam por tipo. Em pagador, uma empresa vem em cnpj no lugar de cpf. Quando a instituição de pagamento só informa o documento de quem pagou mascarado, ele vem como ela o deu em cpfMascarado (ou cnpjMascarado), com o cpf vazio.

A sua resposta #

Responda 2xx assim que receber. Um evento que você recusar ou em que o seu sistema falhar é repetido sozinho e não para os outros. A fila do endereço só pausa quando o endpoint parece fora do ar.

O seu endereço recebe vários eventos ao mesmo tempo, de recursos diferentes. O número se ajusta sozinho: começa em 8 e sobe enquanto o endereço responde 2xx rápido, até 512, e cai quando ele falha ou demora. Os de um mesmo recurso chegam um de cada vez, na ordem da sequencia. O endereço que ainda não respondeu 2xx, ou que falhou depois do último 2xx, recebe um por vez. A recusa de um evento não conta.

Resposta O que acontece
2xx Entregue.
400, 409, 413 ou 422 Recusa deste evento. Ele tenta de novo sozinho e os outros continuam chegando. Os do mesmo recurso esperam atrás dele.
5xx, ou nenhuma resposta em 10 segundos com a conexão aberta Falha deste evento. Ele tenta de novo sozinho e os outros continuam chegando. Os do mesmo recurso esperam atrás dele.
A conexão que não abre (DNS, TLS, conexão recusada), 401, 403, 404, 405, 410 ou outra resposta O endereço está fora. Os eventos que falharam esperam, e um deles testa o endereço até ele voltar. Um evento novo é tentado assim mesmo.

Com 3 eventos diferentes falhando no mesmo endereço, nenhum com um 2xx dele desde a primeira falha, o endereço também pausa. Nenhum evento segura outro: não há limite de eventos recusados, e um evento novo sai mesmo com o endereço pausado. Quando um evento chega com 2xx num endereço pausado, a entrega para ele volta na hora, e um evento que falhou antes desse 2xx, inclusive com 404, passa a tentar sozinho sem pausar o endereço.

A assinatura #

Cada entrega traz o cabeçalho x-jws-signature com uma JWS destacada ES256 sobre o corpo. A chave pública está em GET /.well-known/jwks.json. Verifique antes de confiar no corpo.

Cabeçalhos seus #

Se um firewall ou gateway na frente do seu endpoint exige um token, cadastre até 3 cabeçalhos. Eles vão em toda entrega, na URL geral e nos desvios.

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"
}

Omitir cabecalhos mantém os gravados, {} apaga todos, um nome com null mantém aquele valor e um nome gravado que não vem no objeto é apagado. Trocar a url não apaga os cabeçalhos. A assinatura continua obrigatória: os cabeçalhos vão junto dela, nunca no lugar.

Eventos #

Tipo Quando
pix.recebido O Pix liquidou. Ainda não é saldo. Com situacaoFundos EM_DEVOLUCAO, ele foi recusado e volta ao pagador.
pix.creditado O dinheiro virou saldo. Credite o seu cliente aqui.
pix.retido O Pix entrou e ficou bloqueado.
cob.pagamento_rejeitado Recusamos o pagamento. motivo diz por quê. Se custodia.recusaAntesDoCredito é false em GET /v2/ex/config, o dinheiro entrou e volta ao pagador: seguem pix.recebido com EM_DEVOLUCAO e devolucao.criada.
cob.atualizada A cobrança foi alterada ou cancelada.
devolucao.criada Uma devolução saiu, sua ou nossa. motivo diz qual.
devolucao.concluida A devolução liquidou.
devolucao.nao_realizada A devolução não saiu. Na que você pediu, o banco do pagador a recusou. Na nossa, o Pix não voltou ao pagador e foi creditado a você: o pix.creditado chega à parte, sem ordem garantida entre os dois.
payout.aguardando_aprovacao O saque parou numa regra de aprovação, ou você pediu a aprovação, e espera um gestor no painel. O valor já saiu do disponível. Sem endToEndId.
payout.em_processamento O saque está em envio. Sem aprovação, o valor sai do disponível agora.
payout.realizado O saque liquidou. endToEndId é o definitivo. Traz recebedor quando a instituição informa quem recebeu.
payout.nao_realizado O saque foi recusado. O valor voltou ao disponível.
payout.devolucao_recebida O banco do favorecido devolveu um saque já realizado.
payout.sla.em_risco Faltam 30 minutos para o prazo do saque.
payout.sla.estourado O prazo do saque venceu com ele em curso.
favorecido.criado Alguém cadastrou no painel um destino para saques. Ele já vale: liberaEm é o próprio cadastro. Se você não reconhece, remova.
favorecido.liberado A instituição liberou antes do prazo um destino que esperava. Ele já recebe, e liberaEm diz desde quando. Se você não reconhece, remova.
favorecido.renomeado A instituição corrigiu, a seu pedido, o nome de um destino. Só o nome muda: a chave, o documento e a espera ficam como estavam.
favorecido.removido O destino saiu da lista.
med.infracao.criada Um Pix recebido foi contestado. Veja Contestações.
med.infracao.atualizada A contestação mudou de situação ou teve desfecho.
saldo.bloqueado Parte do saldo foi retida.
saldo.desbloqueado A retenção acabou.
subconta.atualizada Uma sub-conta foi criada, mudou de status ou teve o custodiante trocado. statusAnterior só vem na mudança de status.
conta.status_alterado A sua conta mudou de status.
conta.segmento_alterado A instituição reclassificou a sua conta. Releia GET /v2/ex/config.
conta.custodiante_alterado A sua conta principal passou a viver noutra instituição. custodiante e custodianteAnterior trazem o nome de cada uma. Releia GET /v2/ex/config.
split.executado Um recebimento foi repartido.
split.revertido Uma devolução ou contestação desfez a repartição.
tarifa.cobrada Uma tarifa foi cobrada. Num recebimento, meio é PIX_RECEBIDO e referencia é o txid; num saque realizado, meio é PIX_ENVIADO e referencia é o idEnvio. valor é a tarifa.
webhook.teste Disparado por POST /v2/ex/webhook/teste. Quando chega, a entrega pausada daquele endereço volta a tentar.

Exemplos de cada evento #

O corpo inteiro que o seu endpoint recebe em cada tipo, com valores fictícios. Uma chave nova pode aparecer em dados: ignore a que você não conhece.

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 #

Num recebimento com split vem também split, e numa sub-conta, 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 diz quais regras pararam o saque: PEDIDA, VALOR, QUANTIDADE_DESTINO ou 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 só vem quando a instituição informa quem recebeu.

{
  "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 #

Numa retenção que não é de contestação, como uma ordem judicial, vêm só id, tipo e valor.

{
  "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 diz o que saiu de circulação com o bloqueio.

{
  "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"
  }
}

Saúde da fila #

GET /v2/ex/webhook/saude

Escopo: ex.webhook.read.

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

situacao é OK, ATENCAO ou FALHANDO. Fora de OK vem motivo; em FALHANDO vem também ultimaFalha, com falha RECUSA, ERRO ou INDISPONIBILIDADE. recusadas conta as que o seu endpoint recusou e comErro as em que ele falhou, e as duas seguem tentando. Entregas desistidas não saem mais sozinhas: conserte o endpoint e peça o reenvio.

Reenvio #

POST /v2/ex/webhook/reenvios

Escopo: 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 só conta. soFalhas: true manda só os avisos que falharam: os que esgotaram as tentativas sem o seu endereço aceitar e nunca foram entregues. A janela alcança até 30 dias para trás e inicio não pode estar no futuro; um fim no futuro vale até agora. Sem webhook ativo, o reenvio termina INTERROMPIDO. GET /v2/ex/webhook/reenvios/{id} acompanha um reenvio, GET /v2/ex/webhook/reenvios lista os 10 mais novos, POST /v2/ex/webhook/reenvios/{id}/cancelar cancela o reenvio enquanto algum aviso dele não saiu, também o que já terminou de pôr os avisos na fila (CONCLUIDO): ele passa a INTERROMPIDO, e os avisos dele que ainda não saíram não saem, contados em naoEnviados, GET /v2/ex/webhook/entregas lista as tentativas com status HTTP e latência, filtra por status (PENDENTE, ENTREGUE ou FALHA_PERMANENTE) e continua por ?cursor=, e GET /v2/ex/eventos é o feed dos mesmos envelopes, para reconciliar: ele avança por ?apos= com o cursor.proximo da página anterior. Para ver primeiro o que aconteceu agora, use ?ordem=recentes, que avança por ?antes=.

Erros #

Status title Quando
400 url_invalida A URL não é HTTPS válido.
400 url_privada A URL aponta para rede privada ou localhost, ou o host não resolve no DNS.
400 familia_desconhecida urlsPorFamilia cita uma família que não existe.
400 tipos_invalidos Um item de tiposHabilitados em branco.
400 cabecalho_invalido Nome ou valor fora da forma, o mesmo nome duas vezes com outra caixa, mais de 3, ou null para um nome sem valor gravado.
400 cabecalho_proibido Um cabeçalho da conexão, do corpo ou nosso, como Host, Content-Type ou x-jws-signature.
400 campo_desconhecido Um campo que a rota não conhece, como headers no lugar de cabecalhos.
400 periodo_invalido inicio ou fim do reenvio fora do RFC 3339.
400 janela_invalida fim não é depois de inicio, ou inicio está no futuro.
400 janela_muito_antiga inicio tem mais de 30 dias.
404 nao_encontrado GET ou DELETE sem webhook cadastrado, ou reenvio que não existe.
409 reenvio_em_andamento Já há um reenvio em curso.
409 reenvio_encerrado O reenvio que se quer cancelar já terminou, e todos os avisos dele já saíram.
422 webhook_nao_configurado Teste sem webhook ativo.
503 cabecalhos_indisponiveis A instalação não guarda cabeçalhos agora. Nada foi gravado.