Connections

Overview

The connection.disconnected webhook event is triggered when an OAuth connection between an Airwallex account and a partner application is disconnected. This event is essential for partner applications to proactively detect when they lose access to a connected account, rather than discovering the disconnection when API calls fail.

Use this webhook to:

• Immediately update your application's connection status for affected accounts.
• Notify your users that they need to reconnect their Airwallex account.
• Stop scheduled operations (such as data syncing or payment processing) for the disconnected account.
• Log the disconnection for audit and troubleshooting purposes.

Event types

When this event is triggered

The connection.disconnected event is sent when:

• User disconnects: The Airwallex account owner manually disconnects your application from their account settings.
• Token revocation: OAuth tokens are revoked due to security concerns (for example, refresh token reuse outside the grace period).
• Admin role changes: The user who originally authorized the connection loses their admin permissions (Owner, Admin, or Finance Admin role).
• Account closure: The connected Airwallex account is closed or suspended.

Best practices

1. Set up the webhook before going to production: Ensure you're listening to connection.disconnected events as part of your OAuth integration. See Notifications and workflow automation for setup instructions.
2. Handle the event promptly: Update your database to mark the connection as inactive immediately upon receiving this event.
3. Gracefully inform users: Provide clear messaging in your application when a connection is lost, with an option to reconnect.
4. Implement reconnection flows: Make it easy for users to re-authorize your application when needed.

For more information on handling OAuth token issues and connection problems, see Troubleshoot OAuth errors.

Payload examples

Relevant webhook events:

• connection.disconnected

Payload example:

1{
2    "id": "6d5b23e7-6f12-4179-b3a6-cbefb532798e",
3    "name": "connection.disconnected",
4    "account_id": "acct_istZCPlZO4K0P9isv4RFcg",
5    "data": {
6        "id": "YXBwaWRfSGN1UHp5UkFaem9rN09SYVJzcW06YWNjdF9pc3RaQ1BsWk80SzBQOWlzdjRSRmNn",
7        "account_id": "acct_istZCPlZO4K0P9isv4RFcg",
8        "status": "DISCONNECTED",
9        "authorized_scopes": [
10            "w:awx_action:transfers_edit",
11            "w:awx_action:contact_management_edit",
12            "r:awx_action:balances_view",
13            "r:awx_action:settings.account_details_view"
14        ]
15    },
16    "created_at": "2025-07-24T07:16:00+0000",
17    "version": "2022-11-11",
18    "source_id": "52f3c874-2827-437b-b3d2-a067444951d3"
19}