Listen for webhook events

You can subscribe to webhook events by registering a notification URL. When one of these events is triggered in your account or any account you were authorized to access, Airwallex will notify your application. The notifications are sent to your configured notification URL, as a JSON payload through HTTP POST.

1. Log into the Airwallex web app.
2. Open Developer > Webhooks > Summary page.
3. Click Add Webhook to configure the notification URL and the events you want to listen for.
4. Click a webhook event to preview the payload. You can also test the webhook event against the specified notification URL in the demo environment using the Test event button. For more information, see Test webhook event payloads

HTTP POST payloads that are delivered to your webhook's configured URL endpoint will contain several special headers:

You must acknowledge the notifications we send you. To acknowledge receipt of an event, your endpoint must return a 200 HTTP status code, when either no answer or another response code is received we will retry. Acknowledge events prior to any logic that needs to take place to prevent timeouts.

Airwallex signs the webhook events it sends to your endpoints. We do so by including a signature in each request's header. This allows you to verify that the events were sent by Airwallex. You can verify signatures by following steps.

Before you can verify signatures, you need to retrieve your endpoint's secret from your web app. Each secret is unique to the endpoint to which it corresponds. Additionally, if you have multiple endpoints, you must obtain a secret for each one. After this setup, Airwallex starts to sign each webhook it sends to the endpoint.

1. Extract the x-timestamp and x-signature from the header
2. Prepare the value_to_digest string. You achieve this by concatenating: the x-timestamp (as a string) and the actual JSON payload (the request's body, as a string)
3. Compute an HMAC with the SHA-256 hash function. Use the endpoint's signing secret as the key, and use the value_to_digest string as the message.
4. Compare the x-signature in the header to the expected signature. If a signature matches, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

Common issues : the signature doesn't match

When creating the expected signature, please make sure to use the raw JSON payload.

Note: many libraries tend to format the JSON while parsing the payload, so it's recommended to check the signature before any transformation occurs.

Airwallex emits Webhook calls using one of the following IPs. To receive webhook calls successfully, these IPs must be whitelisted:

For Production Environment

• 35.240.218.67
• 35.185.179.53
• 34.87.64.173
• 35.220.213.251
• 34.92.128.176
• 34.91.47.254
• 34.91.75.229
• 35.230.185.215
• 34.86.42.60

For Demo Environment

• 35.240.211.132
• 35.187.239.216
• 34.87.139.23
• 34.92.48.104
• 34.92.144.250
• 34.92.15.70

Receive events with an HTTPS server

Please use an HTTPS URL for your webhook endpoint for security considerations. Furthermore, your server must be correctly configured to support HTTPS.

Retry logic

If your webhook endpoint is unavailable or takes too long to respond, Airwallex will resend the notification message several times over the course of three days until a successful response is returned.

Acknowledge events immediately

If your webhook script performs complex logic, it's possible that the script would time out before Airwallex sees its complete execution. Ideally, your webhook handling code (acknowledging receipt of an event by returning a 200 status code) is separate from any processing performed for that event.

Handle duplicate events

Webhook endpoints might occasionally receive the same event more than once. We advise you to guard against receiving duplicate events by making your event processing idempotent.

To deduplicate events, please use the "id" field sent on the event. Across retry, the same event keeps the same "id".

Order of events

Airwallex does not guarantee delivery of events in the order in which they are generated. Your endpoint should not expect delivery of these events in this order and should handle this accordingly. You can also use created_at in the event for ordering.