Webhook

您登记一个 HTTPS URL，每发生一个事件就会收到一次 POST。投递带有签名，约 5 小时内尝试 9 次，每个地址有自己的队列：您某个响应慢的端点不会拖慢任何人。

登记 #

PUT /v2/ex/webhook

权限范围：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"
}

字段	类型	必填	说明
`url`	字符串	是	公网 HTTPS 地址。接收所有没有分流的事件。
`tiposHabilitados`	列表	否	`[""]` 表示全部，或填写您需要的类型。缺省为 `[""]`。
`urlsPorFamilia`	对象	否	按族分流。族是类型的第一段，`GET /v2/ex/webhook/familias` 列出可用的族。
`cabecalhos`	对象	否	每次投递都会带上的自定义请求头，最多 3 个。读取时不返回其值。

PUT 描述的是最终状态：省略 urlsPorFamilia 会删除已有的分流。该路由不认识的字段返回 400 campo_desconhecido。GET /v2/ex/webhook 读取配置，DELETE /v2/ex/webhook 停用投递，GET /v2/ex/webhook/familias 列出可用的族。

事件信封 #

每个事件都以如下正文到达。请在 10 秒内响应 2xx，之后再处理。对不认识的类型也请响应 2xx。

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

字段	类型	说明
`eventoId`	字符串	唯一。请据此丢弃重复的事件：投递保证至少一次。
`sequencia`	整数	按资源（`txid`、`idEnvio`）递增。不保证不同资源之间的顺序。
`correlationId`	字符串	产生该事件的请求的 id。可能不出现，例如提现期限的通知。
`dados`	对象	事件内容。键随类型而变。在 `pagador` 中，企业以 `cnpj` 代替 `cpf`。当支付机构只提供付款人证件的遮盖形式时，按其原样放在 `cpfMascarado`（或 `cnpjMascarado`）中，`cpf` 为空。

您的响应 #

收到后请立即响应 2xx。您拒绝的事件，或您系统处理失败的事件，会自动重试，不会阻塞其他事件。只有在端点看起来已经下线时，该地址的队列才会暂停。

您的地址会同时收到多个事件，它们来自不同的资源。这个数量会自动调整：从 8 开始，地址快速响应 2xx 时逐步增加，最多 512；地址失败或响应缓慢时会减少。同一资源的事件按 sequencia 的顺序逐个到达。尚未响应过 2xx 的地址，或在最近一次 2xx 之后失败的地址，每次只收到一个事件。事件被拒绝不计入此规则。

响应	结果
`2xx`	已投递。
`400`、`409`、`413` 或 `422`	拒绝此事件。它会单独重试，其他事件继续到达。同一资源的事件排在它后面等待。
`5xx`，或连接已打开但 10 秒内没有响应	此事件失败。它会单独重试，其他事件继续到达。同一资源的事件排在它后面等待。
无法建立连接（DNS、TLS、连接被拒绝）、`401`、`403`、`404`、`405`、`410` 或其他响应	该地址已下线。失败的事件等待，由其中一个事件测试该地址，直到它恢复。新事件照常尝试。

同一地址上有 3 个不同的事件失败，且自首次失败以来该地址没有返回过任何 2xx 时，该地址也会暂停。任何事件都不会挡住其他事件：被拒绝的事件没有数量上限，即使地址已暂停，新事件也会照常发送。在已暂停的地址上有事件以 2xx 送达时，对该地址的投递立即恢复，在这个 2xx 之前失败的事件（包括 404）会单独重试，不再暂停该地址。

签名 #

每次投递都带有请求头 x-jws-signature，内容是对正文的 ES256 分离式 JWS。公钥在 GET /.well-known/jwks.json。信任正文之前请先验证。

自定义请求头 #

如果您端点前面的防火墙或网关要求令牌，您可以登记最多 3 个请求头。它们随每次投递发送，包括通用 URL 和分流地址。

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

省略 cabecalhos 会保留已记录的请求头，{} 删除全部，名称的值为 null 表示保留该值，已记录但未出现在对象中的名称会被删除。更换 url 不会删除请求头。签名仍然必需：这些请求头与签名一起发送，绝不代替签名。

事件 #

类型	触发时机
`pix.recebido`	Pix 已结算。尚未计入余额。若 `situacaoFundos` 为 `EM_DEVOLUCAO`，表示它被拒绝并退还付款人。
`pix.creditado`	款项已计入余额。请在此时为您的客户入账。
`pix.retido`	Pix 已到账，但被冻结。
`cob.pagamento_rejeitado`	我们拒绝了该付款。`motivo` 说明原因。如果 `GET /v2/ex/config` 中 `custodia.recusaAntesDoCredito` 为 `false`，款项已经到账并会退还付款人：随后会有 `EM_DEVOLUCAO` 的 `pix.recebido` 和 `devolucao.criada`。
`cob.atualizada`	收款被修改或取消。
`devolucao.criada`	一笔退款已发出，可能是您发起的，也可能是我们发起的。`motivo` 说明是哪一种。
`devolucao.concluida`	退款已结算。
`devolucao.nao_realizada`	退款没有发出。您发起的退款，是被付款人的银行拒绝。我们发起的退款，是这笔 Pix 没有退回付款人，已入账给您：`pix.creditado` 会单独送达，两者之间的顺序不作保证。
`payout.aguardando_aprovacao`	提现触发了审批规则，或您要求了审批，正在等待管理员在控制台处理。金额已从可用余额中扣除。不带 `endToEndId`。
`payout.em_processamento`	提现正在发送。无需审批时，金额在此时从可用余额中扣除。
`payout.realizado`	提现已结算。`endToEndId` 为最终值。机构告知收款人时带有 `recebedor`。
`payout.nao_realizado`	提现被拒绝。金额已退回可用余额。
`payout.devolucao_recebida`	收款人的银行退回了一笔已完成的提现。
`payout.sla.em_risco`	距提现期限还剩 30 分钟。
`payout.sla.estourado`	提现期限已过，而提现仍在进行中。
`favorecido.criado`	有人在控制台登记了一个提现目标。它已立即生效：`liberaEm` 就是登记的时间。如果您不认识它，请移除。
`favorecido.liberado`	机构提前放行了一个正在等待的目标。它已可以收款，`liberaEm` 表示生效的时间。如果您不认识它，请移除。
`favorecido.renomeado`	机构应您的要求更正了一个目标的名称。只有名称改变：密钥、证件号和等待期保持不变。
`favorecido.removido`	该目标已从列表中移除。
`med.infracao.criada`	一笔收到的 Pix 被提出争议。见争议。
`med.infracao.atualizada`	争议的状态发生变化，或已有结果。
`saldo.bloqueado`	部分余额被冻结。
`saldo.desbloqueado`	冻结已解除。
`subconta.atualizada`	子账户被创建、状态变更或 `custodiante` 被更换。`statusAnterior` 仅在状态变更时返回。
`conta.status_alterado`	您的账户状态已变更。
`conta.segmento_alterado`	机构对您的账户进行了重新分类。请重新读取 `GET /v2/ex/config`。
`conta.custodiante_alterado`	您的主账户已转到另一家机构。`custodiante` 和 `custodianteAnterior` 分别为两家机构的名称。请重新读取 `GET /v2/ex/config`。
`split.executado`	一笔到账款项已完成分账。
`split.revertido`	退款或争议撤销了分账。
`tarifa.cobrada`	收取了一笔手续费。对于到账，`meio` 为 `PIX_RECEBIDO`，`referencia` 为 `txid`；对于已完成的提现，`meio` 为 `PIX_ENVIADO`，`referencia` 为 `idEnvio`。`valor` 为手续费金额。
`webhook.teste`	由 `POST /v2/ex/webhook/teste` 触发。它到达时，该地址已暂停的投递会重新开始尝试。

每种事件的示例 #

以下是您的端点在每种类型下收到的完整正文，数值均为虚构。dados 中可能出现新的键：忽略您不认识的键即可。

`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` #

带分账的收款还会带 split，子账户的收款还会带 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 说明是哪些规则拦下了提现：PEDIDA、VALOR、QUANTIDADE_DESTINO 或 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。

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

不是由争议产生的冻结（例如法院命令）只带 id、tipo 和 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 说明账户被封锁时停用了哪些内容。

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

队列健康 #

GET /v2/ex/webhook/saude

权限范围：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 或 FALHANDO。不是 OK 时返回 motivo；为 FALHANDO 时还返回 ultimaFalha，其中 falha 为 RECUSA、ERRO 或 INDISPONIBILIDADE。recusadas 统计被您的端点拒绝的投递，comErro 统计您的端点处理失败的投递，两者都会继续重试。已放弃的投递不会再自动发送：请修复端点后申请重新发送。

重新发送 #

POST /v2/ex/webhook/reenvios

权限范围：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 只统计数量。soFalhas: true 只重新发送失败的通知：即用尽所有尝试、您的端点始终未接受、从未送达的通知。时间窗口最多向前追溯 30 天，inicio 不能是将来的时间；将来的 fim 按当前时间处理。没有启用的 webhook 时，重新发送以 INTERROMPIDO 结束。GET /v2/ex/webhook/reenvios/{id} 跟踪一次重新发送，GET /v2/ex/webhook/reenvios 列出最近的 10 次，POST /v2/ex/webhook/reenvios/{id}/cancelar 在重新发送还有通知未发出时将其取消，已把通知全部放入队列（CONCLUIDO）的也可以取消：它变为 INTERROMPIDO，尚未发出的通知不再发送，数量见 naoEnviados，GET /v2/ex/webhook/entregas 列出每次尝试及其 HTTP 状态码和延迟，可按 status（PENDENTE、ENTREGUE 或 FALHA_PERMANENTE）过滤，并通过 ?cursor= 继续读取；GET /v2/ex/eventos 是相同信封的事件流，用于对账：它通过 ?apos= 加上一页的 cursor.proximo 向后推进。要先看刚刚发生的事件，请使用 ?ordem=recentes，它通过 ?antes= 推进。

错误 #

状态码	`title`	触发条件
400	`url_invalida`	URL 不是有效的 HTTPS 地址。
400	`url_privada`	URL 指向私有网络或 localhost，或主机名无法通过 DNS 解析。
400	`familia_desconhecida`	`urlsPorFamilia` 引用了不存在的族。
400	`tipos_invalidos`	`tiposHabilitados` 中有空白项。
400	`cabecalho_invalido`	名称或值格式错误，同一名称以不同大小写出现两次，超过 3 个，或对没有已记录值的名称传了 `null`。
400	`cabecalho_proibido`	属于连接、正文或我们自己的请求头，例如 `Host`、`Content-Type` 或 `x-jws-signature`。
400	`campo_desconhecido`	该路由不认识的字段，例如用 `headers` 代替 `cabecalhos`。
400	`periodo_invalido`	重新发送的 `inicio` 或 `fim` 不符合 RFC 3339。
400	`janela_invalida`	`fim` 不晚于 `inicio`，或 `inicio` 是将来的时间。
400	`janela_muito_antiga`	`inicio` 早于 30 天前。
404	`nao_encontrado`	未登记 webhook 时执行 `GET` 或 `DELETE`，或重新发送不存在。
409	`reenvio_em_andamento`	已有一次重新发送正在进行。
409	`reenvio_encerrado`	要取消的重新发送已经结束，其所有通知都已发出。
422	`webhook_nao_configurado`	没有启用的 webhook 时进行测试。
503	`cabecalhos_indisponiveis`	当前系统暂时无法保存请求头。没有保存任何内容。

Webhook

登记 #

事件信封 #

您的响应 #

签名 #

自定义请求头 #

事件 #

每种事件的示例 #

pix.recebido #

pix.creditado #

pix.retido #

cob.pagamento_rejeitado #

cob.atualizada #

devolucao.criada #

devolucao.concluida #

devolucao.nao_realizada #

payout.aguardando_aprovacao #

payout.em_processamento #

payout.realizado #

payout.nao_realizado #

payout.devolucao_recebida #

payout.sla.em_risco #

payout.sla.estourado #

favorecido.criado #

favorecido.liberado #

favorecido.renomeado #

favorecido.removido #

med.infracao.criada #

med.infracao.atualizada #

saldo.bloqueado #

saldo.desbloqueado #

subconta.atualizada #

conta.status_alterado #

conta.custodiante_alterado #

split.executado #

split.revertido #

tarifa.cobrada #

webhook.teste #