Saltar al contenido principal
Los webhooks permiten que su sistema reaccione a los eventos de transferencia en tiempo real — sin necesidad de polling. Cuando una transferencia se completa, falla o requiere atención, su endpoint recibe una notificación automáticamente.

​
Eventos disponibles

EventoCuándo se activaTipos de transferenciaAcción recomendada
transfer.initiatedRegistro de transferencia creado después de confirmar la iniciaciónTED OUT, P2PActualice el estado de la transferencia en su sistema; muestre “transferencia en curso” al cliente
transfer.pendingTED OUT entró en estado PENDING — enviado a JD SPB, esperando reconocimientoTED OUTMuestre al cliente que la transferencia espera reconocimiento de la red
transfer.processingRetención de transacción Midaz exitosa; la transferencia avanza hacia la finalizaciónTED OUT, P2PMuestre al cliente que la transferencia está siendo procesada
transfer.rejectedJD SPB retornó un rechazo 4xx (datos inválidos, violación de regla)TED OUTNotifique al cliente que la transferencia fue rechazada; fondos ya liberados
transfer.completedTransferencia liquidada exitosamenteP2PNotifique al cliente; genere recibo; actualice la visualización del saldo
transfer.failedLa transferencia alcanzó un fallo terminal por error 5xx o timeout de JD SPBTED OUTNotifique al cliente que la transferencia no se procesó; reembolse si es necesario
transfer.cancelledTransferencia cancelada por el cliente antes del procesamientoTED OUT, P2PConfirme la cancelación al cliente; libere cualquier bloqueo en la interfaz
transfer.incoming.receivedMensaje JD entrante persistido — búsqueda de destinatario aún no iniciadaTED INRegistre el evento; espere transfer.incoming.completed para confirmación final
transfer.incoming.completedTED entrante recibido, destinatario encontrado, crédito aplicadoTED INNotifique al destinatario que los fondos han llegado; actualice la visualización del saldo
transfer.incoming.chargebackMensaje de contracargo recibido para un TED IN previamente completado (STR0010R2)TED INCongele el monto acreditado; inicie revisión con su equipo de cumplimiento
transfer.reconciliation_requiredInconsistencia detectada durante la deduplicaciónTED INMarque para conciliación manual; no acredite hasta que se resuelva
Para TED OUT, el evento transfer.completed aún no se emite. La finalización de TED OUT se confirma de forma asíncrona por SPB y será soportada en una versión futura. Hasta entonces, monitoree el estado de TED OUT a través del endpoint Get Transfer o el endpoint de conciliación.

​
Configurar webhooks

Los webhooks se configuran por organización, de modo que cada tenant puede tener su propio endpoint y secreto. Configure su webhookUrl (debe ser HTTPS) y webhookSecret a través de la configuración de administrador. Para instrucciones de configuración, consulte Configuración TED.

​
Estructura del payload

Todos los eventos webhook siguen el mismo sobre. A continuación se muestra un ejemplo del evento más común, 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 la Referencia de API para los esquemas completos de payload de cada tipo de evento.

​
Manejo de fallas de entrega

Si su endpoint no responde con un estado 2xx dentro de 5 segundos (WEBHOOK_TIMEOUT_MS=5000), el evento se reintenta automáticamente con retroceso exponencial:
IntentoDemora
1Inmediata
21 segundo
32 segundos
44 segundos
58 segundos
Después de 5 intentos fallidos, el evento se mueve a una cola de mensajes no procesables (DLQ). Configure alertas en la DLQ para detectar fallas persistentes de entrega antes de que afecten sus operaciones. Para garantizar una entrega confiable: responda dentro de 5 segundos, use HTTPS con un certificado válido, y devuelva 200 incluso para los eventos que decida ignorar. Delegue cualquier procesamiento pesado a una cola en segundo plano — mantenga su manejador de webhooks ágil.

​
Idempotencia

Su endpoint puede recibir el mismo evento más de una vez. Use el transferId (y el nombre del evento) para deduplicar: si ya procesó esa combinación, devuelva 200 y no realice ninguna acción adicional.

​
Para desarrolladores

Para código de validación de firma (JavaScript, Python, Go), implementación de reintentos y la lista de verificación de integración completa, consulte la guía para desarrolladores TED.