> ## 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       |
| `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/detecting-whatsapp-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"
  }
}
```

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