Skip to main content
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.pendingTED OUT entered PENDING state — submitted to JD SPB, awaiting acknowledgmentTED OUTShow customer that transfer is pending network acknowledgment
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.receivedRaw incoming JD message persisted — recipient lookup not yet startedTED INLog the event; await transfer.incoming.completed for final confirmation
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 follow the same envelope. Here is an example of the most common event, 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"
  }
}
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:
AttemptDelay
1Immediate
21 second
32 seconds
44 seconds
58 seconds
After 5 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. 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.