Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks permitem que seu sistema reaja a eventos de transferência em tempo real — sem necessidade de polling. Quando uma transferência é concluída, falha ou requer atenção, seu endpoint recebe uma notificação automaticamente.

​
Eventos disponíveis

EventoQuando é disparadoTipos de transferênciaAção recomendada
transfer.initiatedRegistro de transferência criado após confirmação da iniciaçãoTED OUT, P2PAtualize o status da transferência no seu sistema; exiba “transferência em andamento” ao cliente
transfer.processingHold de transação no Midaz bem-sucedido; transferência avançando para conclusãoTED OUT, P2PExiba ao cliente que a transferência está sendo processada
transfer.rejectedJD SPB retornou rejeição 4xx (dados inválidos, violação de regra)TED OUTNotifique o cliente que a transferência foi rejeitada; fundos já liberados
transfer.completedTransferência liquidada com sucessoP2PNotifique o cliente; gere recibo; atualize exibição de saldo
transfer.failedTransferência atingiu falha terminal por erro 5xx ou timeout do JD SPBTED OUTNotifique o cliente que a transferência não foi realizada; faça reembolso se necessário
transfer.cancelledTransferência cancelada pelo cliente antes do processamentoTED OUT, P2PConfirme cancelamento ao cliente; libere bloqueios de interface
transfer.incoming.completedTED recebida, destinatário encontrado, crédito aplicadoTED INNotifique o destinatário que os fundos chegaram; atualize exibição de saldo
transfer.incoming.chargebackMensagem de estorno recebida para um TED IN previamente concluído (STR0010R2)TED INBloqueie o valor creditado; inicie revisão com sua equipe de compliance
transfer.reconciliation_requiredInconsistência detectada durante deduplicaçãoTED INMarque para reconciliação manual; não credite até que seja resolvido
Para TED OUT, o evento transfer.completed ainda não é emitido. A conclusão do TED OUT é confirmada de forma assíncrona pelo SPB e será suportada em uma versão futura. Até lá, monitore o status do TED OUT pelo endpoint Obter Transferência ou pelo endpoint de reconciliação.

​
Configuração de webhooks

Os webhooks são configurados por organização, de modo que cada tenant pode ter seu próprio endpoint e segredo. Configure sua webhookUrl (deve ser HTTPS) e webhookSecret por meio da configuração administrativa. Para instruções de configuração, consulte configuração do TED.

​
Estrutura do payload

Todos os eventos de webhook compartilham o mesmo envelope. Os campos do envelope são estáveis entre tipos de evento; o payload específico de cada evento fica dentro de payload.
CampoTipoNotas
eventIdstring (UUID)Identificador único desta emissão de evento. Use-o para deduplicar entregas at-least-once no seu lado.
versionstringVersão do schema do envelope. Atualmente v1.
typestringTipo de evento, ex: transfer.completed.
tenantIdstring (UUID)Organização dona da transferência.
transferIdstring (UUID)Presente em eventos com escopo de transferência; omitido em eventos com escopo de tenant.
correlationIdstringCorrelaciona a cadeia de eventos produzida por uma requisição originária.
causationIdstringOpcional. Id do evento que causou este (para fluxos encadeados).
occurredAtstring (RFC3339, UTC)Quando o evento ocorreu no lado do plugin.
payloadobjectCampos específicos do evento. O schema depende de type (veja abaixo).
metadataobjectMapa opcional string-para-string que carrega hints de tracing e roteamento.
A seguir, um exemplo de transfer.completed para uma transferência P2P: 
{
  "eventId": "019c96a0-ee10-7fff-aaaa-1111aaaa2222",
  "version": "v1",
  "type": "transfer.completed",
  "tenantId": "019c96a0-0a98-7287-9a31-786e0809c769",
  "transferId": "019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d",
  "correlationId": "019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b",
  "occurredAt": "2026-01-21T17:35:00Z",
  "payload": {
    "status": "COMPLETED",
    "transferType": "P2P",
    "midazTransaction": "019c96a0-cd10-7eee-bbbb-3333bbbb4444",
    "confirmationNumber": "20260121001"
  },
  "metadata": {}
}
A forma de payload depende do tipo de evento. Para transfer.completed, os campos são status, transferType, midazTransaction e confirmationNumber (cada um emitido apenas quando definido). Para obter valores, tarifas, dados do destinatário ou timestamps, recupere a transferência via Obter Transferência usando o transferId do envelope.
Consulte a Referência da API para os schemas completos de payload de cada tipo de evento.

​
Tratamento de falhas na entrega

Se o seu endpoint não responder com status 2xx dentro de 5 segundos (WEBHOOK_TIMEOUT_MS=5000), o evento é reenviado automaticamente com backoff exponencial e full jitter. O plugin faz até WEBHOOK_MAX_RETRIES tentativas no total (padrão 3), com um delay base de WEBHOOK_RETRY_BACKOFF_MS (padrão 500 ms) dobrado a cada retry:
TentativaIntervalo antes desta tentativa
1Imediato
2Aleatório em [0, 1000 ms] (base × 2^1)
3Aleatório em [0, 2000 ms] (base × 2^2)
Após 3 tentativas sem sucesso, o evento é movido para uma dead-letter queue (DLQ). Configure alertas na DLQ para identificar falhas persistentes de entrega antes que afetem suas operações. Ajuste WEBHOOK_MAX_RETRIES e WEBHOOK_RETRY_BACKOFF_MS se o seu endpoint precisar de um orçamento de retry mais longo ou mais curto. Para garantir entrega confiável: responda dentro de 5 segundos, use HTTPS com certificado válido e retorne 200 mesmo para eventos que você optar por ignorar. Delegue qualquer processamento pesado para uma fila em segundo plano — mantenha seu handler de webhook rápido.

​
Idempotência

Seu endpoint pode receber o mesmo evento mais de uma vez. Use o transferId (e o nome do evento) para deduplicar: se já tiver processado 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.