Partner connection disconnected event

The partner_connection.disconnected Webhook event notifies your application when all connections between an Airwallex account or organization and your partner application are disconnected. Understanding this event is important when building OAuth-based partner integrations, as it allows your application to detect disconnections in real time and respond without waiting for API calls to fail.

Overview

Partner-level delivery

The partner_connection.disconnected event operates at the partner application level. Once you create a single Webhook subscription, your application receives disconnection notifications for any authorized Airwallex account or organization, without needing to set up separate subscriptions for each account.

The event supports two types of disconnection:

• Organization disconnections: If the disconnection involves an organization, the org_id field is present in the payload.
• Batch account disconnections: A single action in the Airwallex web app may simultaneously disconnect multiple accounts. The account_ids array in the payload reflects all affected accounts.

Event triggers

The partner_connection.disconnected event is sent when an Airwallex account owner or organization administrator manually disconnects your application from their authorization settings.

The reason field in the payload identifies the cause. user_initiated is the only supported reason. Support for additional reasons may be added.

Event payload

The event payload follows the standard Webhook event structure, with app_id at the event level identifying your partner application.

1{
2  "id": "afc52587-8eac-4c3c-b9eb-b48e904e672f",
3  "name": "partner_connection.disconnected",
4  "app_id": "appid_YShMHGlexW8P3ElndQ9H",
5  "data": {
6    "account_ids": [
7      "acct_yETjCx7GPIqDcnp2fYkSww",
8      "acct_grlXIezYOl2EzrBpPuxbXg"
9    ],
10    "org_id": "org_8VxyrkWuSvKe-Yq2NqJ-4Q",
11    "reason": "user_initiated"
12  },
13  "created_at": "2026-05-20T13:54:20+0000",
14  "version": "2026-02-27"
15}

The data object contains the following fields:

Best practices

• Subscribe as part of your OAuth integration: Set up a partner_connection.disconnected subscription before going to production. See Notifications and workflow automation for setup instructions.
• Handle multiple account IDs: Because account_ids may contain more than one account, ensure your handler iterates over the full list and marks all affected connections as inactive.
• Check for org_id: If your integration uses Billing or Spend scopes, also check whether org_id is present and update any organization-level connection state accordingly.
• Respond promptly: Update your database to mark affected connections as inactive immediately upon receiving the event.
• Notify your users: Provide clear messaging when a connection is lost, with an option to reconnect.

See also

To deepen your understanding or see how this concept applies in practice, refer to:

• Notifications and workflow automation
• Troubleshoot OAuth errors