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
`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"
  }
}

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

workflow.execution.handoff

workflow.execution.failed

project.event

​Available events

​whatsapp.phone_number.created

​whatsapp.phone_number.deleted

​workflow.execution.handoff

​workflow.execution.failed

​project.event

Available events

whatsapp.phone_number.created

whatsapp.phone_number.deleted

workflow.execution.handoff

workflow.execution.failed

project.event