Airwallex logo

Getting started with webhooks

Webhooks provide notifications and callbacks that enable you to receive asynchronous notifications of the events on the Airwallex Platform.

Subscription

You can register webhook URLs for Airwallex to notify any time an event happens in your account and any account you were authorized to access. When one of those events is triggered, Airwallex will send a HTTP POST payload to the webhook's configured URL.

  1. Log into the Airwallex webapp
  2. On the left hand nav, go to "Account" and "Developer"
  3. "Add webhook" allows you to configure the webhook URL and the events you want to listen for

Webhook configuration on webapp

Delivery headers

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

HeaderDescription
x-timestampThe Long type timestamp, such as 1357872222592.
x-signatureThe HMAC hex digest of the response body. This header will be sent if the webhook is configured with a secret. The HMAC hex digest is generated using the sha256 hash function and the secret as the HMAC key.

Respond to webhook events

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.

Checking webhook signatures

Airwallex can optionally sign 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 Webapp. 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.