> ## 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.

# Connection Events

> Connection lifecycle webhook events for creation, updates, expiry, and deletion

Connection Events notify your server when an OFAuth connection is created, updated, expires, or is deleted.

## Event Types

| Event                     | Trigger                                                                                               |
| ------------------------- | ----------------------------------------------------------------------------------------------------- |
| `connection.created`      | A new connection is established                                                                       |
| `connection.updated`      | Connection details change, such as permissions after reconnection                                     |
| `connection.expired`      | A connection expires naturally or is [invalidated via API](/guides/connections#invalidate-connection) |
| `connection.disconnected` | A connection is permanently removed from OFAuth via the delete API                                    |

## Payload Format

All connection events share the same general payload shape:

```json theme={null}
{
  "type": "connection.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "clientReferenceId": "user_456",
    "connection": {
      "id": "conn_abc123",
      "status": "active"
    }
  }
}
```

### `connection.created`

```json theme={null}
{
  "type": "connection.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "clientReferenceId": "user_456",
    "connection": {
      "id": "conn_abc123",
      "status": "active",
      "permissions": ["profile:read", "posts:read"],
      "userData": {
        "id": "of_user_456",
        "name": "Jane Doe",
        "username": "janedoe",
        "avatar": "https://cdn.onlyfans.com/avatar.jpg"
      }
    }
  }
}
```

### `connection.updated`

```json theme={null}
{
  "type": "connection.updated",
  "timestamp": "2024-01-15T11:00:00Z",
  "data": {
    "clientReferenceId": "user_456",
    "connection": {
      "id": "conn_abc123",
      "status": "active",
      "permissions": ["profile:read", "posts:read", "messages:read"],
      "userData": {
        "id": "of_user_456",
        "name": "Jane Doe",
        "username": "janedoe",
        "avatar": "https://cdn.onlyfans.com/avatar.jpg"
      }
    }
  }
}
```

### `connection.expired`

```json theme={null}
{
  "type": "connection.expired",
  "timestamp": "2024-01-15T12:00:00Z",
  "data": {
    "clientReferenceId": "user_456",
    "connection": {
      "id": "conn_abc123",
      "status": "expired"
    }
  }
}
```

Use `connection.expired` when the connection record still exists and can be reconnected or renewed.

### `connection.disconnected`

```json theme={null}
{
  "type": "connection.disconnected",
  "timestamp": "2024-01-15T12:05:00Z",
  "data": {
    "clientReferenceId": "user_456",
    "connection": {
      "id": "conn_abc123",
      "status": "disconnected"
    }
  }
}
```

Use `connection.disconnected` when a connection is fully removed from OFAuth and can no longer be reconnected or renewed.

<Tip>
  The `connection.created` event is the recommended way to receive connection IDs. Use `data.clientReferenceId`, which you provided when [initializing Link](/api-reference/link/init), to map the connection to the correct user in your database.
</Tip>