Listen for webhook events

Create a webhook subscription, configure your endpoint to respond and verify signatures, and whitelist Airwallex IPs so you receive webhook notifications. For an overview of how webhooks work, delivery behavior, and security, refer to Webhooks overview.

Before you begin

You need access to the Airwallex web app with Developer, Admin, or Owner role.

Create a webhook subscription

You subscribe by registering a notification URL and choosing which events to receive. When one of those events occurs in your account, Airwallex sends a JSON payload to your URL via HTTP POST.

To create a webhook subscription:

1. Log in to the Airwallex web app and select Settings > Developer > Webhooks.
2. Click New webhook to configure the notification URL and the events you want to listen for.
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 is set to the API version configured for your account, but you can choose a different API version.
4. Select the events the webhook will listen for. You can listen to events across multiple accounts using the Account dropdown.
5. Click Submit to create a webhook subscription.

Delivery headers

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

In the payload, the id field corresponds to Event ID in the web app; the data object is the event payload.

Respond to webhook events

Your endpoint must acknowledge all notifications by returning a 200 OK HTTP status code. If Airwallex does not receive a 200 OK response (due to a timeout or any other status code), it considers the delivery a failure and retries. To prevent timeouts, send the 200 OK response immediately.

Check webhook signatures

Airwallex signs the webhook events it sends to your notification URLs 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 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.

Code examples

The following examples show how to verify the signature and return 200 for success or 400 if verification fails, in Java, PHP, and Node.js.

1import org.apache.commons.codec.digest.HmacAlgorithms;
2import org.apache.commons.codec.digest.HmacUtils;
3import org.springframework.stereotype.Controller;
4import org.springframework.web.bind.annotation.PostMapping;
5import org.springframework.web.bind.annotation.RequestBody;
6import org.springframework.web.bind.annotation.ResponseBody;
7
8import javax.servlet.http.HttpServletRequest;
9import javax.servlet.http.HttpServletResponse;
10
11@Controller
12public class WebhookExampleController {
13
14  @PostMapping("/webhook/example")
15  @ResponseBody
16  public String receive(HttpServletRequest request, @RequestBody String payload, HttpServletResponse response) {
17    String responseBody = "";
18
19    StringBuilder valueToDigest = new StringBuilder();
20    String timestamp = request.getHeader("x-timestamp");
21    valueToDigest.append(timestamp);
22    valueToDigest.append(payload);
23
24    String signature = request.getHeader("x-signature");
25    String secret = getSecret();
26
27    HmacUtils hmacUtils = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, secret);
28    if (hmacUtils.hmacHex(valueToDigest.toString()).equals(signature)) {
29      // Do something with event
30      response.setStatus(HttpServletResponse.SC_OK);
31    } else {
32      response.setStatus(HttpServletResponse.SC_BAD_REQUEST);
33      responseBody = "failed to verify the signature";
34    }
35
36    return responseBody;
37  }
38}

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

For guidance on HTTPS, retries, acknowledging events immediately, handling duplicate events, and event ordering, refer to Webhooks overview.

Next steps

Now that you can receive and verify webhooks, you can:

• View and re-trigger webhook events to inspect events and re-deliver them in the web app.
• Review event types and payload examples by product.