How do I set up Airwallex webhook-driven reconciliation?

Register a notification URL with Airwallex and choose which event types to receive, over HTTPS with your server allow-listing Airwallex's webhook IPs. Verify every request's HMAC signature before trusting it, and handle events idempotently by tracking each event's id — Airwallex retries failed deliveries and doesn't guarantee order, so your reconciliation logic has to tolerate both.

By Zuny Fester, Head of Operations and Marketing

Reviewed by Zuny Fester

Published September 14, 2026Last reviewed September 14, 2026Editorial policy

Part of the finance integrations guide.

Transport requirement	HTTPS only, with Airwallex's webhook IP ranges allow-listed on your endpoint
Trust step	Verify the HMAC signature on every request before processing it
Delivery guarantee	At-least-once, retried on non-200 responses; order is not guaranteed
Dedup key	Each event's id field stays stable across retries of the same event
Recovery window	Events are retained 30 days and can be manually re-triggered from the Airwallex dashboard

Why this is worth setting up over polling

Loopfour's Airwallex integration has a full webhook handler pipeline — event verification, normalization, matching, registration — rather than polling Airwallex's API on a schedule. That means reconciliation state can update within seconds of a payout settling, instead of waiting for the next poll cycle. The tradeoff is that a webhook endpoint has real setup requirements Airwallex enforces, not optional hardening.

What actually has to be true before events arrive

Airwallex's own documentation is specific about two requirements before it will deliver anything: the endpoint must be HTTPS, and it must accept traffic from Airwallex's published webhook IP ranges. Neither is a suggestion — an endpoint that fails either check simply won't receive events, and there's no separate error to debug beyond "nothing is arriving."

Why signature verification isn't optional

Airwallex signs every webhook request with HMAC over the timestamp and body, specifically so a receiving endpoint can confirm a request actually came from Airwallex and wasn't tampered with in transit. Skipping this check means anything that can reach your public endpoint — not just Airwallex — can trigger reconciliation logic by sending a payload shaped like a real event.

Why idempotency has to be designed in from day one

Because Airwallex retries any delivery that doesn't get a 200 response, and doesn't guarantee delivery order, the same event can legitimately arrive more than once, and a later event can arrive before an earlier one. The fix for both is the same field: every event carries an id that stays constant across retries. Track which ids have already been processed and skip duplicates; sort or key state by each event's created_at rather than the order requests physically arrived in.

Next step

Map the finance workflow with the most exposure and prove the automation path.

Bring the invoice, contract, payment reconciliation, or customer finance workflow you have to defend at audit. Loopfour can map the trigger, controls, integrations, and approval loop.

Book a workflow review

Checklist

Airwallex webhook setup, in the order Airwallex actually requires it

Stand up an HTTPS endpoint and allow-list Airwallex's published webhook IP ranges on it — before registering anything.
Register a webhook subscription in the Airwallex dashboard: the notification URL plus the specific event types you want. Loopfour's integration is registered for payment_attempt.paid, payment_attempt.settled, deposit.settled, and deposit.pending — there is no payout-specific event type to subscribe to.
Implement HMAC signature verification on every incoming request before any other processing — reject anything that doesn't verify.
Store each processed event's id and check new events against it before acting, so a retried delivery is a no-op, not a duplicate reconciliation entry.
Respond 200 as fast as possible — do slow work (lookups, matching) after acknowledging receipt, since a slow or failed response is exactly what triggers a retry.

Frequently Asked Questions

Airwallex treats a non-200 response or a timeout as a failed delivery and retries with exponential back-off for about three days; after that, the event can still be found and manually re-triggered from the dashboard for up to 30 days.

No — a single subscription can select multiple event types; you don't need to register a new endpoint for each one.

If near-real-time reconciliation isn't required, polling avoids the operational overhead of running and securing a public endpoint — but it trades that for latency between a payment or deposit settling and your system knowing about it.

Sources

Integration

Why don't my Stripe payouts tie to the NetSuite bank deposit?

A Stripe payout rarely equals one NetSuite deposit line: Stripe nets many charges, fees, and refunds into one transfer settled days later. Check, in order: the payout isn't unbundled into individual charges, the deposit date doesn't match the transaction date, fees are netted not booked separately, a partial capture created a variance, or the payout is still in Undeposited Funds.

Topic

Integrations

Every finance automation vendor publishes an integrations page: a grid of logos, a claim of "seamless" connectivity, and not much else. That page answers a marketing question — does this vendor touch…

Diagnostic

What breaks when Airwallex webhooks arrive out of order during payout reconciliation?

Airwallex does not guarantee webhook delivery in the order events were generated. A deposit.settled event can arrive before the deposit.pending event that should precede it, so reconciliation logic that assumes sequential arrival can build a match against incomplete state. Order by each event's created_at timestamp and deduplicate by its id, not by arrival order.