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",
    "external_id": "CUS-12345"
  }
}

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",
    "external_id": "CUS-12345"
  }
}

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",
    "external_id": "CUS-12345"
  },
  "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"
  },
  "customer": {
    "id": "880e8400-e29b-41d4-a716-446655440003",
    "external_id": "CUS-12345"
  },
  "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 contain lowercased Meta values and are null when Meta does not provide them.

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 reaching the WhatsApp Business Account (WABA).

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.

You receive one delivery per project and WABA, with the affected numbers listed in phone_numbers - not one delivery per number.

Most enforcement is account-wide and phone_numbers lists every number in the project on that WABA. whatsapp.account.restricted and whatsapp.account.violation can also target a single number: when Meta identifies one, the payload carries a top-level phone_number (or phone_number_id) and phone_numbers contains only that number. whatsapp.account.disabled and whatsapp.account.reinstated are always account-wide.

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	The affected numbers in the project on that WABA. Every number on the WABA for account-wide enforcement, or only the targeted number when phone_number or phone_number_id is present
phone_number	Only on whatsapp.account.restricted and whatsapp.account.violation targeting a single number, when Meta identified it by display phone number. Normalized digits, without + or separators
phone_number_id	Only on whatsapp.account.restricted and whatsapp.account.violation targeting a single number, when Meta identified it by phone number id instead
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.

A restriction targeting a single number:

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

If the targeted number is not in your project, no delivery is sent for it, and the other numbers on the WABA are left untouched.

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.