Pular para o conteúdo principal
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.pendingTED OUT entrou no estado PENDING — enviado ao JD SPB, aguardando reconhecimentoTED OUTExiba ao cliente que a transferência aguarda reconhecimento da rede
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.receivedMensagem JD recebida persistida — busca de destinatário ainda não iniciadaTED INRegistre o evento; aguarde transfer.incoming.completed para confirmação final
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 seguem o mesmo envelope. Veja um exemplo do evento mais comum, transfer.completed: 
{
  "event": "transfer.completed",
  "timestamp": "2026-01-21T14:35:00-03:00",
  "organizationId": "019c96a0-0a98-7287-9a31-786e0809c769",
  "data": {
    "transferId": "019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d",
    "type": "P2P",
    "status": "COMPLETED",
    "confirmationNumber": "20260121001",
    "amount": 500.00,
    "feeAmount": 0.00,
    "totalAmount": 500.00,
    "completedAt": "2026-01-21T14:35:00-03:00"
  }
}
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:
TentativaIntervalo
1Imediato
21 segundo
32 segundos
44 segundos
58 segundos
Após 5 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. 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.