Webhooks

Webhooks permitem que seu sistema reaja a eventos de transferência em tempo real, sem polling. O plugin envia uma notificação ao seu endpoint quando uma transferência é concluída, falha ou requer atenção.

Eventos disponíveis

Cada evento indica os tipos de transferência a que se aplica (entre parênteses), quando é disparado e a ação recomendada.

Ciclo de vida da transferência (TED OUT, P2P)

`transfer.initiated` (TED OUT)

Disparo: o plugin criou o registro de transferência TED OUT após confirmar a iniciação.
Ação: atualize o status da transferência no seu sistema. Exiba “transferência em andamento” ao cliente.

`transfer.processing_started` (TED OUT)

Disparo: a transferência TED OUT entrou em processamento (caminho de status CREATED para PENDING para PROCESSING).
Ação: exiba ao cliente que a transferência está em andamento.

`transfer.rejected` (TED OUT)

Disparo: o JD SPB rejeitou a solicitação de transferência antes de aceitá-la (dados inválidos ou violação de regra).
Ação: notifique o cliente sobre a rejeição. O plugin já cancelou a retenção de fundos.

`transfer.completed` (P2P)

Disparo: a transferência P2P foi liquidada com sucesso.
Ação: notifique o cliente. Gere um recibo. Atualize a exibição de saldo.

Reconciliação (TED OUT, TED IN)

`transfer.reconciliation_required`

Disparo: uma transferência com desfecho desconhecido passou para reconciliação.
Ação: acompanhe a transferência como pendente. Não presuma sucesso ou falha.

`transfer.reconciliation_resolved`

Disparo: a reconciliação foi concluída e a transferência atingiu um desfecho definitivo.
Ação: atualize a transferência para seu status final.

`transfer.reconciliation_exhausted`

Disparo: a reconciliação parou após o número máximo de tentativas.
Ação: escale a transferência para revisão manual por um operador.

`transfer.reconciliation_failed`

Disparo: uma tentativa de reconciliação encontrou um erro determinístico, que falhou a transferência.
Ação: trate a transferência como falha e investigue.

Transferências recebidas (TED IN)

`transfer_incoming.completed`

Disparo: o plugin recebeu uma TED de entrada, encontrou o destinatário e aplicou o crédito.
Ação: notifique o destinatário que os fundos chegaram. Atualize a exibição de saldo.

`transfer_incoming.chargeback`

Disparo: uma mensagem de estorno chegou para um TED IN concluído (STR0010R2).
Ação: bloqueie o valor creditado. Inicie uma revisão com sua equipe de compliance.

`transfer_incoming.undeliverable`

Disparo: o plugin não pôde creditar uma TED de entrada (por exemplo, não encontrou a conta do destinatário).
Ação: investigue a transferência. O plugin pode devolvê-la ao banco de origem.

Devoluções e iniciação

`transfer_outgoing.devolution_notified` (TED OUT)

Disparo: uma devolução chegou para uma transferência de saída.
Ação: reconcilie os fundos devolvidos com a transferência original.

`payment_initiation.created` (TED OUT, P2P)

Disparo: o plugin criou uma iniciação de pagamento (a etapa pré-transferência).
Ação: opcional. Acompanhe iniciações que aguardam confirmação.

Para TED OUT, o plugin ainda não emite transfer.completed. O SPB confirma a conclusão do TED OUT de forma assíncrona, e uma versão futura adicionará este evento. Até lá, consulte o status do TED OUT com o endpoint Get Transfer ou o endpoint de reconciliação.

Configuração de webhooks

Os webhooks funcionam por tenant. Você registra um destino de uma de duas formas. API self-service (recomendada). Registre um ou mais endpoints HTTPS através da API de registro de webhooks. O servidor gera um signingSecret na criação e o retorna uma única vez. Armazene-o com segurança. Use-o para verificar a assinatura em cada evento entregue. Você também pode listar, atualizar, desabilitar e excluir registros, rotacionar o signing secret e consultar os tipos de evento aceitos. O plugin deriva o tenant dono do bearer token, nunca de um cabeçalho de requisição.

Criar um registro de webhook — POST /v1/webhooks
Listar registros de webhook — GET /v1/webhooks
Obter, atualizar e excluir um registro
Rotacionar o signing secret — POST /v1/webhooks/{webhookId}/signing-secret/rotate
Listar tipos de evento suportados — GET /v1/webhooks/event-types

Habilitando a entrega (operador/env). Defina WEBHOOK_ENABLED=true para ativar a entrega de saída. A entrega também requer RabbitMQ e a streaming outbox (STREAMING_ENABLED=true). Os destinos vêm dos registros acima. Não há uma única variável de ambiente de endpoint estático. Você ajusta o comportamento por entrega — timeout e máximo de retentativas — em runtime através do systemplane, não por variáveis de ambiente. Consulte Configuração do Bank Transfer.

Estrutura do payload

O plugin entrega cada evento como um POST HTTPS. O corpo da requisição é o payload do evento em JSON. O tipo de evento e a assinatura viajam em cabeçalhos HTTP, não no corpo.

Cabeçalho	Valor
`Content-Type`	`application/json`.
`X-Webhook-Event`	O tipo de evento, por exemplo `transfer.completed`.
`X-Webhook-Timestamp`	Hora de entrega como timestamp Unix (segundos). A assinatura cobre este valor.
`X-Webhook-Signature`	Assinatura HMAC-SHA256 sobre o timestamp e o corpo, com a chave do `signingSecret` do registro. Formato: `v1,sha256=<hex>`.

Os campos do corpo dependem do tipo de evento. Cada payload inclui tenantId, e os eventos com escopo de transferência também incluem transferId. Os valores são strings decimais na moeda da conta, não centavos (por exemplo, 100.00). A seguir, um exemplo de corpo para transfer.completed em uma transferência P2P:

{
  "transferId": "019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d",
  "initiationId": "019c96a0-9a01-7bcd-e0f1-2a3b4c5d6e7f",
  "tenantId": "019c96a0-0a98-7287-9a31-786e0809c769",
  "ledgerId": "019c96a0-1b20-7def-a1b2-c3d4e5f60718",
  "senderAccountId": "019c96a0-2c30-7ef0-b2c3-d4e5f6071829",
  "recipientAccountId": "019c96a0-3d40-7f01-c3d4-e5f60718293a",
  "midazTransactionId": "019c96a0-cd10-7eee-bbbb-3333bbbb4444",
  "confirmationNumber": "20260121001",
  "status": "COMPLETED",
  "transferType": "P2P",
  "amount": "100.00",
  "feeAmount": "0.00",
  "totalAmount": "100.00",
  "completedAt": "2026-01-21T17:35:00Z"
}

O payload de transfer.completed inclui os valores, as contas e o midazTransactionId. Para eventos com um payload menor, ou para ler o registro completo da transferência, recupere a transferência em Get Transfer com o seu transferId.

Os campos do payload diferem conforme o tipo de evento. Para ler todos os campos de uma transferência, use o endpoint Get Transfer.

Tratamento de falhas na entrega

Seu endpoint deve responder com status 2xx dentro de 5 segundos (o valor padrão de webhook.timeout_ms). Se não responder, o plugin repete a entrega com backoff exponencial e full jitter. Após a primeira tentativa, o plugin faz até 3 tentativas adicionais (o valor padrão de webhook.max_retries), o que dá 4 tentativas de entrega no total. A base do backoff é 1 segundo e dobra a cada tentativa. O full jitter se aplica a cada intervalo:

Tentativa	Intervalo antes desta tentativa
1 (inicial)	Imediato
2	Aleatório em `[0, 1000 ms]`
3	Aleatório em `[0, 2000 ms]`
4	Aleatório em `[0, 4000 ms]`

Após todas as tentativas falharem (4 por padrão), o evento é movido para uma dead-letter queue (DLQ). Configure alertas na DLQ para identificar falhas persistentes de entrega cedo. Ajuste webhook.max_retries através do systemplane se o seu endpoint precisar de um orçamento de retry mais longo ou mais curto. O knob webhook.retry_backoff_ms controla o backoff de reconexão ao broker, não o cronograma de retry HTTP por entrega acima. Para uma entrega confiável, siga estas regras:

Responda dentro de 5 segundos.
Use HTTPS com um certificado válido.
Retorne 200 mesmo para os eventos que você ignorar.
Mova o processamento pesado para uma fila em segundo plano. Mantenha o handler de webhook rápido.

Idempotência

Seu endpoint pode receber o mesmo evento mais de uma vez. Use o transferId do corpo e o cabeçalho X-Webhook-Event para deduplicar. Se já processou essa combinação, retorne 200 e não execute nenhuma ação adicional.

Para desenvolvedores

Para código de validação de assinatura (JavaScript, Python, Go), implementação de retry e o checklist completo de integração, consulte o guia do desenvolvedor TED.

Visão geral

Lerian SPB — mensageria nativa

JD — interface

BTG — interface

Console

Eventos disponíveis

Ciclo de vida da transferência (TED OUT, P2P)

`transfer.initiated` (TED OUT)

`transfer.processing_started` (TED OUT)

`transfer.rejected` (TED OUT)

`transfer.completed` (P2P)

Reconciliação (TED OUT, TED IN)

`transfer.reconciliation_required`

`transfer.reconciliation_resolved`

`transfer.reconciliation_exhausted`

`transfer.reconciliation_failed`

Transferências recebidas (TED IN)

`transfer_incoming.completed`

`transfer_incoming.chargeback`

`transfer_incoming.undeliverable`

Devoluções e iniciação

`transfer_outgoing.devolution_notified` (TED OUT)

`payment_initiation.created` (TED OUT, P2P)

Configuração de webhooks

Estrutura do payload

Tratamento de falhas na entrega

Idempotência

Para desenvolvedores

​Eventos disponíveis

​Ciclo de vida da transferência (TED OUT, P2P)

​transfer.initiated (TED OUT)

​transfer.processing_started (TED OUT)

​transfer.rejected (TED OUT)

​transfer.completed (P2P)

​Reconciliação (TED OUT, TED IN)

​transfer.reconciliation_required

​transfer.reconciliation_resolved

​transfer.reconciliation_exhausted

​transfer.reconciliation_failed

​Transferências recebidas (TED IN)

​transfer_incoming.completed

​transfer_incoming.chargeback

​transfer_incoming.undeliverable

​Devoluções e iniciação

​transfer_outgoing.devolution_notified (TED OUT)

​payment_initiation.created (TED OUT, P2P)

​Configuração de webhooks

​Estrutura do payload

​Tratamento de falhas na entrega

​Idempotência

​Para desenvolvedores

Eventos disponíveis

Ciclo de vida da transferência (TED OUT, P2P)

`transfer.initiated` (TED OUT)

`transfer.processing_started` (TED OUT)

`transfer.rejected` (TED OUT)

`transfer.completed` (P2P)

Reconciliação (TED OUT, TED IN)

`transfer.reconciliation_required`

`transfer.reconciliation_resolved`

`transfer.reconciliation_exhausted`

`transfer.reconciliation_failed`

Transferências recebidas (TED IN)

`transfer_incoming.completed`

`transfer_incoming.chargeback`

`transfer_incoming.undeliverable`

Devoluções e iniciação

`transfer_outgoing.devolution_notified` (TED OUT)

`payment_initiation.created` (TED OUT, P2P)

Configuração de webhooks

Estrutura do payload

Tratamento de falhas na entrega

Idempotência

Para desenvolvedores