Project webhooks

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. 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 for implementation guide. Payload:

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

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

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

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

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

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

{
  "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 for emitting and triggering workflows from project events.

Getting started

WhatsApp

For your team

Onboard customers

Automations

Available events

whatsapp.phone_number.created

whatsapp.phone_number.deleted

whatsapp.phone_number.offboarded

whatsapp.phone_number.disconnected

whatsapp.phone_number.reconnected

workflow.execution.handoff

workflow.execution.failed

project.event

​Available events

​whatsapp.phone_number.created

​whatsapp.phone_number.deleted

​whatsapp.phone_number.offboarded

​whatsapp.phone_number.disconnected

​whatsapp.phone_number.reconnected

​workflow.execution.handoff

​workflow.execution.failed

​project.event

Available events

whatsapp.phone_number.created

whatsapp.phone_number.deleted

whatsapp.phone_number.offboarded

whatsapp.phone_number.disconnected

whatsapp.phone_number.reconnected

workflow.execution.handoff

workflow.execution.failed

project.event