Webhook Infrastructure Migration

We're moving webhook delivery all our legacy webhooks PAYMENT_STATUS_CHANGE, FX_STATUS_CHANGE, and BENEFICIARY_STATUS_CHANGE) to our new webhook delivery system. It adds delivery authentication, self-service subscription management, full delivery history, and event replay.

Webhook type	Switchover date
PAYMENT_STATUS_CHANGE	13/Oct/2026
FX_STATUS_CHANGE	13/Oct/2026
BENEFICIARY_STATUS_CHANGE	13/Oct/2026

📘
Note:
No action needed to keep receiving events Your existing webhook URLs move over automatically — no need to re-register them — as long as they meet the updated endpoint requirements below.

⚠️ Breaking changes

Endpoints must use HTTPS on port 443, resolve to a public IP, and respond directly — redirects are no longer followed

✨ New

auth-N headers — cryptographically verify that a delivery came from us
Self-service subscriptions — manage URLs, topics, and status from the Developer page
Delivery history — every request/response, searchable via the portal or API
Replay — resend a single delivery or an entire time range
Failure notifications — get an email when a delivery fails
Test deliveries — check connectivity before you go live

📘
Payload structure
Payload structure is unchanged payload and its fields keep the same names, types, and position. Three fields — companyId, eventType, createdAt — are added alongside it, not inside it.

Every webhook now shares the same envelope. Three fields are added at the top level, next to the existing payload object:

Field	Description
companyId	The company the event belongs to (the sub-account's ID, on a parent's copy)
eventType	The webhook type, e.g. PAYMENT_STATUS_CHANGE
createdAt	When the event was created (ISO 8601, UTC)

The contents of payload are unchanged.

Before

{
  "payload": {
    "id": 10001,
    "type": "iban_to_wallet",
    "state": "completed",
    "amount": "500.00",
    "currency": "EUR",
    "reference": "REF-IBAN-001"
  }
}

After

{
  "companyId": "comp-123",
  "eventType": "PAYMENT_STATUS_CHANGE",
  "createdAt": "2026-10-15T10:30:00.000Z",
  "payload": {
    "id": 10001,
    "type": "iban_to_wallet",
    "state": "completed",
    "amount": "500.00",
    "currency": "EUR",
    "reference": "REF-IBAN-001"
  }
}

Sub-accounts and parent companies

The top-level companyId is always set, and tells you which company the event came from. We recommend using it going forward, rather than payload.companyId.

📘
Note:
No action needed if you already read from payload. Ignore any top-level fields you don't recognise.