Create webhook

Subscribe to WhatsApp events for this number.

Two webhook types available:

• kapso: Event-based webhooks with filtered events, buffering support, and Kapso payload format
• meta: Raw Meta webhook forwarding - receives the exact payload Meta sends, with X-Idempotency-Key header

Use buffering (kapso only) to batch high-volume events like inbound messages. Without buffering, each message triggers an immediate webhook delivery.

POST /whatsapp/phone_numbers/{phone_number_id}/webhooks

cURL

basic

curl --request POST \
  --url https://api.kapso.ai/platform/v1/whatsapp/phone_numbers/{phone_number_id}/webhooks \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "whatsapp_webhook": {
    "url": "https://api.acme.com/webhooks/whatsapp",
    "secret_key": "wh_sec_3kfj9dmfkg8s2",
    "events": [
      "whatsapp.message.received",
      "whatsapp.message.sent"
    ],
    "active": true
  }
}
'

201

{
  "data": {
    "id": "9e8d7c6b-5a4f-3e2d-1c0b-9a8f7e6d5c4b",
    "url": "https://api.acme.com/webhooks/whatsapp",
    "events": [
      "whatsapp.message.received",
      "whatsapp.message.sent"
    ],
    "active": true,
    "secret_key": "wh_sec_3kfj9dmfkg8s2",
    "headers": {
      "X-Webhook-Source": "kapso"
    },
    "buffer_enabled": false,
    "buffer_window_seconds": null,
    "max_buffer_size": null,
    "buffer_events": [],
    "inactivity_minutes": 60,
    "project_id": "1d6ca0a3-91c2-4f13-8a94-28ddb0d5f2f3",
    "phone_number_id": "1234567890",
    "created_at": "2025-07-14T15:00:00Z",
    "updated_at": "2025-07-14T15:00:00Z"
  }
}

Authorizations

X-API-Key · string · header · required

Path Parameters

phone_number_id · string · required

Body

application/json

whatsapp_webhook · Kapso webhook · object · required

Event-based delivery in Kapso's payload format. This is the shape you get when kind is omitted, and it needs at least one event.

Kapso webhook

Meta webhook

Show child attributes

Response

201

application/json

Created

data · object · required

Show child attributes