Skip to content
Last updated

Webhooks and notifications

Listen for events to trigger actions in your workflow.

Webhooks are user-defined callbacks triggered by certain events in Wise's system.

Use webhook notifications to keep your application informed about Wise events and use the details in a webhook payload to trigger specific actions and workflows.

Common webhook events include (but are not limited to):

Event Description
Transfer state changesNotifies you when a transfer's state changes.
Transfer payout failuresNotifies you when a transfer payout fails and includes a reason code and description.
Profile state changesNotifies you when a profile's state changes.
Verification state changesNotifies you when the verification state of a profile changes.
Balance updatesNotifies you every time a multi-currency account is credited or debited.
Card status changesNotifies you when a card status changes, including the initial card status.
Card order status changesNotifies you every time a card order status is updated.
SWIFT message receiptNotifies you when a SWIFT message is received and processed by Wise on your behalf.
Bulk settlement payment receiptNotifies you when a bulk settlement fund is received.
Webhook event payloads do not contain any personally identifiable information (PII).

Webhook subscriptions

The Wise API supports two subscription types:

  • Application-level webhooks: These subscriptions send notifications for events related to resources created by your application.
  • Profile-level webhooks: These subscriptions send notifications when events occur for resources created under a specific Wise profile.

In most cases, you should subscribe to the application-level webhook.

You can subscribe to specific webhook events either programmatically or via Developer Hub. Review the Subscribe to webhooks guide for details on both options.

Webhook delivery

All webhook callbacks use HTTP POST requests. When a business event occurs and a webhook is created, Wise sends an HTTP POST request.

The webhook is considered successfully processed only when we receive a 200 response.

Retry policy

In the event that an HTTP request fails, we retry according to the following policy:

Exponential backoff

By default, we retry HTTP failure responses using an exponential backoff algorithm.

We start with an initial delay of 1 minute, with a growth factor of two and a maximum delay of 24 hours. This results in the following retry sequence:

  • First retry with a 1-min delay.
  • Second retry with a 2-min delay.
  • Third retry with a 4-min delay.
  • ...
  • After the eleventh retry, there are 14 more retries once a day.

Retry-after headers

Wise respects retry-after headers.

We can handle both http-date and delay-seconds responses.

For example:

  • If you return Retry-After: Wed, 21 Oct 2015 07:28:00 GMT we wait until that time to retry, or retry immediately if the date is in the past.
  • If you return Retry-After: 180 we wait 180 seconds until we retry.

Non-recoverable client errors

The following HTTP statuses almost always fail on retry. We will attempt to deliver them up to three times only.

Status codeName
400Bad Request
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
409Conflict
410Gone
417Expectation Failed
422Unprocessable Content

While Wise has a robust retry mechanism, webhook delivery is done on a best-effort guarantee. Please contact us if you believe you missed any webhook events.

Webhook URLs

Before proceeding, make sure the endpoint where you intend to receive webhooks satisfies the following requirements:

  • Has a valid domain name (IPs are disallowed).
  • Listens to HTTPS requests on port 443.
  • Has a valid HTTPS certificate signed by a trusted Certificate Authority (CA). Self-signed or expired certificates are not accepted.
  • Does not include any query arguments in the URL.
  • Responds directly with a 2xx status code. Redirects are not supported. Any 3xx status code (301, 302, 307, etc) is recognized as a delivery error and the redirect will not be followed.

Examples

  • Valid URL: https://webhooks.example.com/balance-change
  • Invalid URL: http://webhooks.example.com:8080/hook.php?type=balance

You can have multiple subscriptions per event type, but be mindful that you will receive duplicate callbacks, one for each subscription.

IP allowlisting (optional)

If your webhook endpoint sits behind a firewall, WAF, or API gateway that blocks unknown source IPs, you must allowlist Wise’s webhook sender IPs. If you don’t, Wise can still generate events, but your network can drop the webhook requests before they reach your application.

  • Prefer CIDR ranges in production: To maximise availability (including scaling and disaster recovery), allowlist the full CIDR ranges where possible. Individual IPs can change and have a lower reliability SLO.
  • Don’t use IP allowlisting as your only security control: IP allowlisting is a network control. You should still use HTTPS and implement the webhook security controls described in this guide (for example, mTLS and/or payload verification where applicable).

Production

Allowlist both CIDR blocks to support regional failover:

  • 45.129.54.0/24 (Frankfurt, eu-central-1)
  • 45.129.55.0/24 (Paris, eu-west-3)

If you can’t allowlist a /24, allowlist these individual IPs instead:

  • 45.129.54.176/32
  • 45.129.54.183/32
  • 45.129.54.106/32
  • 18.184.162.75/32
  • 52.58.50.91/32
  • 18.184.251.153/32
  • 18.197.211.225/32
  • 18.197.211.10/32
  • 18.197.211.120/32

Sandbox

Allowlist these IPs for webhook delivery in Sandbox:

  • 18.199.110.249/32
  • 3.67.109.66/32
  • 3.78.113.13/32
  • 35.157.106.141/32
  • 54.93.137.122/32
  • 18.196.39.9/32