Webhooks overview

Webhooks enable Airwallex to send instant, real-time push notifications to your application when events occur in your Airwallex account. Understanding how webhooks work helps you design a reliable integration, especially for asynchronous outcomes such as payment confirmation or chargebacks that do not follow immediately from an API call.

How webhooks work

You create a webhook subscription by registering a notification URL and choosing which events to receive. When one of those events occurs in your account, Airwallex sends an HTTP POST request to your URL with a JSON payload. Your endpoint must respond with a 200 status code so that Airwallex can confirm delivery. Each event has a stable id so you can safely handle retries and avoid processing the same event twice. To create a subscription and configure your endpoint, refer to Listen for webhook events.

You can also view and re-trigger webhook events in the Airwallex web app to inspect delivery status (success, queued, or failed) and re-deliver events after downtime or for debugging.

Delivery and reliability

Airwallex treats any response other than 200 OK, or a timeout, as a failed delivery and retries. Retries use exponential back-off over about three days until your endpoint returns 200.

• Duplicate events. Your endpoint may receive the same event more than once. Implement idempotent handling by tracking the event id in the payload; that id is unchanged for the same event across retries.
• Order of events. Airwallex does not guarantee that events are delivered in the order they were generated. Do not rely on delivery order; use the created_at field in the payload when you need ordering.

Security and verification

Airwallex signs each webhook request so you can verify that it came from Airwallex and was not modified. Signing uses an HMAC with the request timestamp and body; you compare the computed value to the signature in the request header. Each subscription has its own secret key in the Airwallex web app. Verifying the signature before parsing or processing the payload is a critical security step.

Your webhook endpoint should use HTTPS, and your server must allow traffic from Airwallex’s webhook IP addresses. The list of IPs for production and Sandbox is provided in Listen for webhook events.

See also

To set up or manage webhooks, you can:

• Listen for webhook events to create subscriptions, respond correctly, and verify signatures.
• View and re-trigger webhook events to inspect events and re-deliver them in the web app.