Saltar al contenido 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.

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.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.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 comparten el mismo envelope. Los campos del envelope son estables entre tipos de evento; el payload específico de cada evento vive dentro de payload.
CampoTipoNotas
eventIdstring (UUID)Identificador único de esta emisión de evento. Úselo para deduplicar entregas at-least-once en su lado.
versionstringVersión del schema del envelope. Actualmente v1.
typestringTipo de evento, p. ej., transfer.completed.
tenantIdstring (UUID)Organización propietaria de la transferencia.
transferIdstring (UUID)Presente en eventos con alcance de transferencia; omitido en eventos con alcance de tenant.
correlationIdstringCorrelaciona la cadena de eventos producida por una solicitud originaria.
causationIdstringOpcional. Id del evento que causó este (para flujos encadenados).
occurredAtstring (RFC3339, UTC)Cuándo ocurrió el evento del lado del plugin.
payloadobjectCampos específicos del evento. El schema depende de type (vea más abajo).
metadataobjectMapa opcional string-a-string que transporta hints de tracing y enrutamiento.
A continuación, un ejemplo de transfer.completed para una transferencia 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": {}
}
La forma de payload depende del tipo de evento. Para transfer.completed, los campos son status, transferType, midazTransaction y confirmationNumber (cada uno emitido solo cuando está definido). Para obtener montos, tarifas, datos del destinatario o marcas de tiempo, recupere la transferencia mediante Get Transfer usando el transferId del envelope.
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 y full jitter. El plugin realiza hasta WEBHOOK_MAX_RETRIES intentos en total (predeterminado 3), con un retraso base de WEBHOOK_RETRY_BACKOFF_MS (predeterminado 500 ms) duplicado en cada reintento:
IntentoDemora antes de este intento
1Inmediata
2Aleatoria en [0, 1000 ms] (base × 2^1)
3Aleatoria en [0, 2000 ms] (base × 2^2)
Después de 3 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. Ajuste WEBHOOK_MAX_RETRIES y WEBHOOK_RETRY_BACKOFF_MS si su endpoint necesita un presupuesto de reintentos más largo o más corto. 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.