Skip to main content

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 let your system react to transfer events in real time — no polling required. When a transfer completes, fails, or requires attention, your endpoint receives a notification automatically.

​
Available events

EventWhen it firesTransfer typesRecommended action
transfer.initiatedTransfer record created after initiation is confirmedTED OUT, P2PUpdate transfer status in your system; show “transfer in progress” to the customer
transfer.processingMidaz transaction hold succeeded; transfer advancing toward completionTED OUT, P2PShow customer that transfer is being processed
transfer.rejectedJD SPB returned a 4xx rejection (invalid data, rule violation)TED OUTNotify customer that transfer was rejected; funds already released
transfer.completedTransfer settled successfullyP2PNotify customer; generate receipt; update balance display
transfer.failedTransfer reached a terminal failure due to 5xx error or timeout from JD SPBTED OUTNotify customer that transfer did not go through; refund if needed
transfer.cancelledTransfer cancelled by customer before processingTED OUT, P2PConfirm cancellation to customer; release any UI locks
transfer.incoming.completedInbound TED received, recipient found, credit appliedTED INNotify recipient that funds have arrived; update balance display
transfer.incoming.chargebackChargeback message received for a previously completed TED IN (STR0010R2)TED INFreeze the credited amount; initiate review with your compliance team
transfer.reconciliation_requiredInconsistency detected during deduplicationTED INFlag for manual reconciliation; do not credit until resolved
For TED OUT, the transfer.completed event is not yet emitted. TED OUT completion is confirmed asynchronously by SPB and will be supported in a future release. Until then, monitor TED OUT status via the Get Transfer endpoint or the reconciliation endpoint.

​
Configuring webhooks

Webhooks are configured per organization, so each tenant can have its own endpoint and secret. Set your webhookUrl (must be HTTPS) and webhookSecret through the admin configuration. For setup instructions, see TED configuration.

​
Payload structure

All webhook events share the same envelope. Envelope fields are stable across event types; the per-event payload sits inside payload.
FieldTypeNotes
eventIdstring (UUID)Unique id of this event emission. Use it for at-least-once dedupe on your side.
versionstringEnvelope schema version. Currently v1.
typestringEvent type, e.g. transfer.completed.
tenantIdstring (UUID)Organization that owns the transfer.
transferIdstring (UUID)Present for transfer-scoped events; omitted for tenant-scoped events.
correlationIdstringCorrelates the chain of events produced by one originating request.
causationIdstringOptional. Id of the event that caused this one (for chained workflows).
occurredAtstring (RFC3339, UTC)When the event occurred on the plugin side.
payloadobjectEvent-specific fields. Schema depends on type (see below).
metadataobjectOptional string-to-string map carrying tracing and routing hints.
Here is an example of transfer.completed for a P2P transfer: 
{
  "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": {}
}
The payload shape is per-event-type. For transfer.completed, the fields are status, transferType, midazTransaction, and confirmationNumber (each emitted only when set). To retrieve amounts, fees, recipient details, or timestamps, fetch the transfer via Get Transfer using the envelope’s transferId.
See the API Reference for full payload schemas for each event type.

​
Handling delivery failures

If your endpoint does not respond with a 2xx status within 5 seconds (WEBHOOK_TIMEOUT_MS=5000), the event is retried automatically with exponential backoff and full jitter. The plugin makes up to WEBHOOK_MAX_RETRIES attempts in total (default 3), with a base delay of WEBHOOK_RETRY_BACKOFF_MS (default 500 ms) doubled on each retry:
AttemptDelay before this attempt
1Immediate
2Random in [0, 1000 ms] (base × 2^1)
3Random in [0, 2000 ms] (base × 2^2)
After 3 unsuccessful attempts, the event moves to a dead-letter queue (DLQ). Set up alerts on the DLQ to catch persistent delivery failures before they affect your operations. Tune WEBHOOK_MAX_RETRIES and WEBHOOK_RETRY_BACKOFF_MS if your endpoint needs a longer or shorter retry budget. To ensure reliable delivery: respond within 5 seconds, use HTTPS with a valid certificate, and return 200 even for events you choose to ignore. Offload any heavy processing to a background queue — keep your webhook handler fast.

​
Idempotency

Your endpoint may receive the same event more than once. Use the transferId (and the event name) to deduplicate: if you have already processed that combination, return 200 and take no further action.

​
For developers

For signature validation code (JavaScript, Python, Go), retry implementation, and the full integration checklist, see the TED developer guide.