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.

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
whatsapp.account.disabled	Meta disables the WhatsApp Business Account
whatsapp.account.restricted	Meta restricts capabilities on the WhatsApp Business Account
whatsapp.account.reinstated	Meta reinstates a previously disabled WhatsApp Business Account
whatsapp.account.violation	Meta reports a policy violation on the WhatsApp Business Account
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
kapso_agent.run.approval_required	An API-triggered agent run needs a tool approval
kapso_agent.run.completed	An API-triggered agent run completes
kapso_agent.run.failed	An API-triggered agent run fails
kapso_agent.run.cancelled	An API-triggered agent run is cancelled

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.

Account enforcement events

whatsapp.account.disabled, whatsapp.account.restricted, whatsapp.account.reinstated and whatsapp.account.violation report Meta enforcement against the WhatsApp Business Account (WABA), not against a single number.

Like the phone number lifecycle events, they are only available on project-scoped webhooks using payload version v2. Subscribing with payload_version: "v1" returns 422.

Because the underlying Meta payloads carry no phone number, you receive one delivery per project and WABA, with every affected number listed in phone_numbers - not one delivery per number.

Payload:

{
  "id": "wae_9f2c1d7b8a4e3f5069c1b2a3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f607",
  "event": "whatsapp.account.restricted",
  "occurred_at": "2026-08-14T12:00:00.000000Z",
  "business_account_id": "102290129340398",
  "project": {
    "id": "990e8400-e29b-41d4-a716-446655440004"
  },
  "phone_numbers": [
    {
      "id": "123456789012345",
      "display_phone_number": "[phone]"
    }
  ],
  "restrictions": [
    {
      "type": "RESTRICTED_BIZ_INITIATED_MESSAGING",
      "expires_at": "2026-09-14T12:00:00Z"
    }
  ],
  "source": {
    "provider": "meta",
    "event": "ACCOUNT_RESTRICTION"
  }
}

Field	Description
id	Stable event id, unique per project, WABA and underlying Meta event
phone_numbers	Every number in the project on that WABA
restrictions	Present on whatsapp.account.restricted. type is the raw Meta restriction type; expires_at is omitted when the restriction has no expiry
violation	Present on whatsapp.account.violation: type is the raw Meta violation type, with an optional remediation string
ban	Present on whatsapp.account.disabled and whatsapp.account.reinstated: state is DISABLE or REINSTATE, with an optional date_label string that Meta sends already localized and formatted
source.event	The raw Meta account update event that produced this notification (ACCOUNT_RESTRICTION, ACCOUNT_VIOLATION or DISABLED_UPDATE)

Keys with no value are omitted from the payload.

whatsapp.account.disabled and whatsapp.account.reinstated both come from Meta’s DISABLED_UPDATE event, split by ban state:

{
  "id": "wae_9f2c1d7b8a4e3f5069c1b2a3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f607",
  "event": "whatsapp.account.disabled",
  "occurred_at": "2026-08-14T12:00:00.000000Z",
  "business_account_id": "102290129340398",
  "project": {
    "id": "990e8400-e29b-41d4-a716-446655440004"
  },
  "phone_numbers": [
    {
      "id": "123456789012345",
      "display_phone_number": "[phone]"
    }
  ],
  "ban": {
    "state": "DISABLE",
    "date_label": "August 7, 2026"
  },
  "source": {
    "provider": "meta",
    "event": "DISABLED_UPDATE"
  }
}

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.

Kapso Agent run events

Fire when a Kapso Agent run triggered through the Agent API needs approval, completes, fails, or is cancelled. Runs started from the dashboard or Slack don’t emit these events.

Payload (kapso_agent.run.completed):

{
  "id": "3c0f1a5b9d8e7f6a4b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a",
  "event": "kapso_agent.run.completed",
  "created_at": "2026-08-21T14:35:00Z",
  "data": {
    "run_id": "990e8400-e29b-41d4-a716-446655440004",
    "session_id": "880e8400-e29b-41d4-a716-446655440003",
    "status": "completed",
    "agent": { "type": "mode", "id": "api" },
    "result": { "type": "message", "content": "..." },
    "metadata": {},
    "created_at": "2026-08-21T14:30:00Z",
    "started_at": "2026-08-21T14:30:05Z",
    "finished_at": "2026-08-21T14:35:00Z",
    "status_url": "/platform/v1/kapso-agent/runs/990e8400-e29b-41d4-a716-446655440004"
  }
}

kapso_agent.run.approval_required includes pending_approval with the tool name and parameters. Failed and cancelled runs include error with code (run_failed or run_cancelled) and message. Null fields are omitted.