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
connection.disconnected	A connection is permanently removed from OFAuth via the delete API

Payload Format

All connection events share the same general payload shape:

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

connection.created

{
  "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

{
  "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

{
  "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

{
  "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.

The connection.created event is the recommended way to receive connection IDs. Use data.clientReferenceId, which you provided when initializing Link, to map the connection to the correct user in your database.