> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ofauth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# System Webhook Events

> Authorization and linked account lifecycle events

These events tell your app when access changes. Each event identifies the user’s approval with `authorizationId` and the linked account with `linkedAccountId`. When a change affects the whole authorization, `linkedAccountId` is null. See [Webhooks](https://docs.ofauth.com/v3/api-reference/webhooks.md) for the full event fields and signature checks.

Use `authorization.*` events when access changes for the accounts in one authorization. Use `linked_account.*` events to pause, resume, or stop work for one account. If an account expires, ask the user to reconnect it. If an authorization is revoked, ask the user to approve your app again.

## Lifecycle events

One action sends one event. Changes to the whole authorization are `authorization.*`. Changes to one account are `linked_account.*`, sent to every authorization that includes that account.

| Type | When | `data.reason` | Typical handling |
| - | - | - | - |
| `authorization.granted` | An owner approved your app and a new authorization was created. | `authorized` | Store the account ids under `authorization_id`. |
| `authorization.updated` | The owner approved access again and changed the accounts or permissions, or shared a new account automatically ([auto-add](https://docs.ofauth.com/v3/api-reference/link/authorize.md#accounts-linked-later)). | `consent_updated`, `auto_added` | Add and remove accounts in your records. Re-read scopes from `GET /v3/linked-accounts` when `scopes_changed` is `true`. |
| `authorization.revoked` | The whole authorization ended. | `holder_revoked`, `oauth_revocation`, `integration_deleted`, `integration_suspended` | Delete the stored refresh tokens. The user must authorize again. |
| `linked_account.expired` | One account needs a reconnect. Your access remains. | `provider_session_expired` | Pause operations for the account. |
| `linked_account.reconnected` | One account works again after the owner reconnected it. | `reconnected` | Resume operations. |
| `linked_account.disconnected` | One account no longer works for this authorization. | `owner_removed`, `owner_disconnected`, `owner_deleted`, `developer_deleted` | Stop operations for the account and remove it from your records. |

`authorization.revoked` reasons:

| Reason | Cause |
| - | - |
| `holder_revoked` | The owner disconnected your app from their dashboard. |
| `oauth_revocation` | The application ended the whole authorization with `DELETE /v3/authorization`. |
| `integration_deleted` | Your integration was deleted. |
| `integration_suspended` | Your integration was suspended. |

`linked_account.disconnected` reasons:

| Reason | Cause |
| - | - |
| `owner_removed` | The owner removed this account from your authorization. |
| `owner_disconnected` | The owner disconnected the account from OFAuth. |
| `owner_deleted` | The owner deleted the account. |
| `developer_deleted` | You called `DELETE /v3/linked-accounts/{id}`. |

### Payloads

Event data contains IDs only. Get names, status, and scopes from [`GET /v3/linked-accounts`](https://docs.ofauth.com/v3/api-reference/account/linked-accounts#list-linked-accounts).

| Type | `data` fields |
| - | - |
| `authorization.granted` | `authorization_id`, `reason`, `linked_account_ids` |
| `authorization.updated` | `authorization_id`, `reason`, `scopes_changed`, `added_linked_account_ids`, `removed_linked_account_ids` |
| `authorization.revoked` | `authorization_id`, `reason`, `linked_account_ids` |
| `linked_account.*` | `authorization_id`, `linked_account_id`, `reason` |

```json theme={null}
{
  "authorization_id": "external_live_example123",
  "reason": "auto_added",
  "scopes_changed": false,
  "added_linked_account_ids": ["conn_example123"],
  "removed_linked_account_ids": []
}
```

An event lists up to 100 account IDs. If there are more, it replaces the ID lists with `linked_account_ids_truncated: true` and `linked_account_count`. If access is still active, it also includes `linked_accounts_url: "/v3/linked-accounts"`. Get the full list with that authorization’s access token. A revoked authorization cannot read the list, so `authorization.revoked` events omit `linked_accounts_url`.

```json theme={null}
{
  "authorization_id": "external_live_example123",
  "reason": "authorized",
  "linked_account_ids_truncated": true,
  "linked_account_count": 240,
  "linked_accounts_url": "/v3/linked-accounts"
}
```

Individual credential refresh, expiry, or revocation does not end durable consent and does not send `authorization.revoked`. Each destination can enable lifecycle deliveries with `lifecycleEventsEnabled`; lifecycle deliveries are not billed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.