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

# Project webhooks

> Events sent to project-scoped webhooks - connections, workflow executions, and custom events

Project webhooks are scoped to the whole project rather than a single phone number. They never receive message or conversation events - for those, see [Message events](/docs/platform/webhooks/message-events).

Configure them in **Integrations → Webhooks → Platform webhooks**.

## Available events

| Event                                | Fires when                                                                   |
| ------------------------------------ | ---------------------------------------------------------------------------- |
| `whatsapp.phone_number.created`      | A customer connects WhatsApp through a setup link                            |
| `whatsapp.phone_number.deleted`      | A phone number is removed from your project                                  |
| `whatsapp.phone_number.offboarded`   | Meta offboards a phone number from the Cloud API                             |
| `whatsapp.phone_number.disconnected` | Meta reports that your partner access was removed or the app was uninstalled |
| `whatsapp.phone_number.reconnected`  | Meta reports that the Cloud API connection was restored                      |
| `workflow.execution.handoff`         | A workflow hands off to a human agent                                        |
| `workflow.execution.failed`          | A workflow execution fails                                                   |
| `project.event`                      | A custom project event is emitted                                            |

Sent only to project webhooks. These do not include message or conversation events.

## whatsapp.phone\_number.created

Fires when a customer successfully connects their WhatsApp through a setup link.

See [Connection detection](/docs/platform/setup-links/detect-connection) for implementation guide.

**Payload**:

```json theme={null}
{
  "phone_number_id": "123456789012345",
  "project": {
    "id": "990e8400-e29b-41d4-a716-446655440004"
  },
  "customer": {
    "id": "880e8400-e29b-41d4-a716-446655440003"
  }
}
```

## whatsapp.phone\_number.deleted

Fires when a WhatsApp phone number is removed from your project. This event triggers at the start of the teardown process, before the number is fully deleted.

**Payload**:

```json theme={null}
{
  "phone_number_id": "123456789012345",
  "project": {
    "id": "990e8400-e29b-41d4-a716-446655440004"
  },
  "customer": {
    "id": "880e8400-e29b-41d4-a716-446655440003"
  }
}
```

## whatsapp.phone\_number.offboarded

Fires when Meta offboards a phone number from the Cloud API.

These three events (`offboarded`, `disconnected`, `reconnected`) are only available on project-scoped webhooks using payload version `v2`. Subscribing with `payload_version: "v1"` returns `422`.

**Payload**:

```json theme={null}
{
  "id": "wae_9f2c1d7b8a4e3f5069c1b2a3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f607",
  "event": "whatsapp.phone_number.offboarded",
  "occurred_at": "2026-08-14T12:00:00.000000Z",
  "phone_number_id": "123456789012345",
  "project": {
    "id": "990e8400-e29b-41d4-a716-446655440004"
  },
  "customer": {
    "id": "880e8400-e29b-41d4-a716-446655440003"
  },
  "connection_type": "dedicated",
  "source": {
    "provider": "meta",
    "event": "ACCOUNT_OFFBOARDED",
    "business_account_id": "102290129340398"
  }
}
```

| Field             | Description                                                        |
| ----------------- | ------------------------------------------------------------------ |
| `id`              | Stable event id, unique per phone number and underlying Meta event |
| `connection_type` | `dedicated` or `coexistence`                                       |
| `customer`        | Present only when the number belongs to a customer                 |
| `source.event`    | The raw Meta account update event that produced this notification  |

## whatsapp.phone\_number.disconnected

Fires when Meta reports that your partner access to the number was removed (`PARTNER_REMOVED`) or the partner app was uninstalled (`PARTNER_APP_UNINSTALLED`). The number can no longer send or receive messages through Kapso until it is reconnected.

Same payload as `whatsapp.phone_number.offboarded`, plus a `disconnection` object with the lowercased Meta values:

```json theme={null}
{
  "id": "wae_9f2c1d7b8a4e3f5069c1b2a3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f607",
  "event": "whatsapp.phone_number.disconnected",
  "occurred_at": "2026-08-14T12:00:00.000000Z",
  "phone_number_id": "123456789012345",
  "project": {
    "id": "990e8400-e29b-41d4-a716-446655440004"
  },
  "connection_type": "dedicated",
  "source": {
    "provider": "meta",
    "event": "PARTNER_REMOVED",
    "business_account_id": "102290129340398"
  },
  "disconnection": {
    "reason": "primary_inactivity",
    "initiated_by": "system"
  }
}
```

`disconnection.reason` and `disconnection.initiated_by` come straight from Meta and may be absent.

## whatsapp.phone\_number.reconnected

Fires when Meta reports that the Cloud API connection was restored (`ACCOUNT_RECONNECTED`). Same payload as `whatsapp.phone_number.offboarded`, with `source.event` set to `ACCOUNT_RECONNECTED`.

## workflow\.execution.handoff

Fires when a workflow execution is handed off to a human agent.

**Payload**:

```json theme={null}
{
  "event": "workflow.execution.handoff",
  "occurred_at": "2025-12-08T12:00:00Z",
  "project_id": "990e8400-e29b-41d4-a716-446655440004",
  "workflow_id": "880e8400-e29b-41d4-a716-446655440001",
  "workflow_execution_id": "770e8400-e29b-41d4-a716-446655440002",
  "status": "handoff",
  "tracking_id": "track-abc123",
  "channel": "whatsapp",
  "whatsapp_conversation_id": "conv_789",
  "handoff": {
    "reason": "User requested human assistance",
    "source": "agent_tool"
  }
}
```

| Field            | Description                                                            |
| ---------------- | ---------------------------------------------------------------------- |
| `handoff.reason` | Optional reason provided during handoff                                |
| `handoff.source` | `agent_tool` (from agent step) or `action_step` (from workflow action) |

## workflow\.execution.failed

Fires when a workflow execution fails due to an error.

**Payload**:

```json theme={null}
{
  "event": "workflow.execution.failed",
  "occurred_at": "2025-12-08T12:00:00Z",
  "project_id": "990e8400-e29b-41d4-a716-446655440004",
  "workflow_id": "880e8400-e29b-41d4-a716-446655440001",
  "workflow_execution_id": "770e8400-e29b-41d4-a716-446655440002",
  "status": "failed",
  "tracking_id": "track-abc123",
  "channel": "whatsapp",
  "whatsapp_conversation_id": "conv_789",
  "error": {
    "message": "Workflow execution timed out"
  }
}
```

## project.event

Fires when a custom project event is emitted.

This event is only available on project-scoped webhooks. Phone-number webhooks do not receive custom project events.

Subscribing to this event requires project events to be available on your plan.

**Payload**:

```json theme={null}
{
  "id": "990e8400-e29b-41d4-a716-446655440004",
  "event": "project.event",
  "name": "lead.qualified",
  "occurred_at": "2026-06-27T14:30:00.000000Z",
  "project_id": "880e8400-e29b-41d4-a716-446655440003",
  "conversation_id": "770e8400-e29b-41d4-a716-446655440002",
  "properties": {
    "score": 92,
    "source": "pricing_page"
  }
}
```

`conversation_id` is included only when the event is linked to a WhatsApp conversation.

See [Events](/docs/platform/events) for emitting and triggering workflows from project events.