Listen for webhook events

Webhooks enable Airwallex to send instant, real-time push notifications to your application on events that occur in your Airwallex organization or account(s). This is especially useful for asynchronous events where the result does not follow immediately after an API call, for example, payment confirmation, payment chargeback, etc.

For information on organization and accounts, see Global Entity Management .

Webhooks

You can subscribe to webhook events by registering a notification URL. When one of these events is triggered in your organization or any account(s) 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.

Follow these steps to create webhook subscriptions:

1. Log in to the Airwallex web app and select Settings > Developer > Webhooks.
2. Click New subscription to configure the notification URL and the events you want to listen for, at the organization level or account level.
3. In the Create webhook page, provide the following information.
   • Name: The name for your webhook subscription.
   • Notification URL: The URL the webhook notifications should be sent to.
   • API version: The API version for your webhooks, which determines the structure of the notifications you receive, including event names and payload fields. By default, it will be set to the API version configured for your account, but you can choose to use a different API version.
4. Select the events the webhook will listen for.
   • You may select events across both organization and account(s).
   • You may select one or more accounts using the Account(s) dropdown.
5. Click Submit to create a webhook subscription.

Delivery headers

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

Respond to webhook events

Your endpoint must acknowledge all notifications by returning a 200 OK HTTP status code. If we do not receive a 200 OK response (due to a timeout or any other status code), we will consider the delivery a failure and retry. To prevent timeouts, you must send the 200 OK response immediately, before processing any complex logic.

Check webhook signatures

Airwallex signs the webhook events it sends to your notification URLs. We do so by including a signature in each request's header. This allows you to verify that the events were sent by Airwallex.

Before you can verify signatures, you need to retrieve your notification URL's secret key from your web app. Each secret is unique to the URL to which it corresponds. After this setup, Airwallex starts to sign each webhook it sends to the URL.

You can verify signatures by following these steps.

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 notification URL's secret key as the key and 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.

If your signature verification fails, check the following common causes:

• Use the raw JSON payload: Always use the original, unmodified request body when computing the signature. Do not use a parsed and re-serialized JSON object, as this may change the formatting (whitespace, key ordering, etc.) and result in a different signature.
• Check before parsing: Many JSON parsing libraries automatically format or normalize the JSON payload. Verify the signature before parsing or transforming the payload in any way.
• Verify timestamp format: Ensure you're using the x-timestamp value exactly as received in the header, without any conversion or formatting.
• Use the correct secret key: Confirm you're using the secret key that corresponds to the specific notification URL receiving the webhook. Each webhook subscription has its own unique secret key.
• Check the concatenation order: The value_to_digest string must be constructed by concatenating the x-timestamp (as a string) followed by the raw JSON payload body, in that exact order.

Whitelist IP addresses

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 sandbox 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

Tips for using webhooks

• Receive events with an HTTPS server: Please use an HTTPS URL for your webhook endpoint for security considerations. Additionally, 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 handler performs complex logic, it may time out if it does not respond within 10 seconds, and Airwallex will not receive confirmation that it completed. Ideally, your webhook endpoint should acknowledge the event immediately by returning a 200 status code, and perform any additional processing asynchronously.
• Handle duplicate events: Your endpoint may receive duplicate events. You should make your event handling idempotent by tracking the event id. This id remains constant for the same event, even during retries, allowing you to check if you have already processed it.
• 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 the created_at field in the event payload for ordering.