> ## Documentation Index > Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create project webhook > Create a webhook for this project. Two scoping options: - **Project-scoped**: Omit `phone_number_id` to receive project events only - **Number-scoped**: Include `phone_number_id` to receive message and conversation events for that number Project webhooks do not receive message or conversation events. Use a number-scoped webhook (or `POST /whatsapp/phone_numbers/{phone_number_id}/webhooks`) for those. Subscribing to `project.event` requires project events to be available on your plan. Two webhook types: - **kapso**: Event-based webhooks with filtered events, buffering support, and Kapso payload format - **meta**: Raw Meta webhook forwarding - receives the exact payload Meta sends (requires `phone_number_id`) ## OpenAPI ````yaml /api/platform/v1/openapi-platform.yaml post /whatsapp/webhooks openapi: 3.1.0 info: title: Kapso Platform API version: 0.2.0 description: > Build WhatsApp messaging into your product. Manage customers, connect phone numbers, send broadcasts, and handle conversations. servers: - url: https://api.kapso.ai/platform/v1 description: Production security: - ApiKeyAuth: [] tags: - name: Customers description: Manage customer accounts - name: Setup Links description: WhatsApp onboarding via embedded signup - name: Phone Numbers description: Connect and manage WhatsApp numbers - name: Webhooks description: Subscribe to WhatsApp events - name: Display Names description: Update WhatsApp business display names - name: Broadcasts description: | Send template messages at scale **Alpha**: This API is in alpha and subject to change - name: Conversations description: Manage conversation state - name: Media description: Upload media files for WhatsApp messaging - name: Users description: Manage project team members - name: Inbox Embeds description: Create and manage embeddable inbox access links - name: Webhook Deliveries description: View webhook delivery attempts and their status - name: External API Logs description: View logs of external API calls made by the project - name: Log Search description: Search log events across API, Meta, workflow, and webhook sources - name: Events description: Emit and query project-scoped events - name: Provider Models description: List available AI provider models - name: WhatsApp Flows description: Build interactive WhatsApp Flows for surveys and forms - name: Contacts description: Manage WhatsApp contacts paths: /whatsapp/webhooks: post: tags: - Webhooks summary: Create project webhook description: > Create a webhook for this project. Two scoping options: - **Project-scoped**: Omit `phone_number_id` to receive project events only - **Number-scoped**: Include `phone_number_id` to receive message and conversation events for that number Project webhooks do not receive message or conversation events. Use a number-scoped webhook (or `POST /whatsapp/phone_numbers/{phone_number_id}/webhooks`) for those. Subscribing to `project.event` requires project events to be available on your plan. Two webhook types: - **kapso**: Event-based webhooks with filtered events, buffering support, and Kapso payload format - **meta**: Raw Meta webhook forwarding - receives the exact payload Meta sends (requires `phone_number_id`) operationId: createWhatsappProjectWebhook requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WhatsappProjectWebhookRequest' examples: project_scoped: summary: Project-wide webhook value: whatsapp_webhook: url: https://api.acme.com/webhooks/whatsapp secret_key: wh_sec_3kfj9dmfkg8s2 events: - whatsapp.phone_number.created - whatsapp.phone_number.deleted number_scoped: summary: Number-specific webhook value: whatsapp_webhook: url: https://api.acme.com/webhooks/whatsapp phone_number_id: '1234567890' secret_key: wh_sec_3kfj9dmfkg8s2 events: - whatsapp.message.received - whatsapp.message.sent responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/WhatsappWebhookResponse' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' '422': $ref: '#/components/responses/ValidationError' components: schemas: WhatsappProjectWebhookRequest: type: object required: - whatsapp_webhook properties: whatsapp_webhook: type: object required: - url properties: url: type: string format: uri description: Webhook delivery endpoint phone_number_id: type: string description: >- Optional Meta phone number ID. Omit for project-scoped webhooks (project events only). Required for message/conversation events and all meta webhooks. kind: type: string enum: - kapso - meta default: kapso description: > Webhook type: - **kapso**: Event-based webhooks with filtered events, buffering support, and Kapso payload format (default) - **meta**: Raw Meta webhook forwarding - receives the exact payload Meta sends. Requires phone_number_id. secret_key: type: - string - 'null' description: Secret for request verification active: type: boolean description: Enable deliveries buffer_enabled: type: boolean description: >- Batch messages before delivery (not supported for 'meta' webhooks) buffer_window_seconds: type: - integer - 'null' description: Seconds to wait (1-60, default 5) max_buffer_size: type: - integer - 'null' description: Max messages per batch (1-100) inactivity_minutes: type: - integer - 'null' description: Minutes before inactivity event events: type: array description: >- Event subscriptions (project events for project-scoped webhooks, message/conversation events for number-scoped webhooks) items: type: string buffer_events: type: array description: Events to buffer (not supported for 'meta' webhooks) items: type: string headers: type: - object - 'null' additionalProperties: true description: Custom request headers payload_version: type: - string - 'null' description: Webhook payload format version (defaults to 'v2') WhatsappWebhookResponse: type: object required: - data properties: data: $ref: '#/components/schemas/WhatsappWebhook' WhatsappWebhook: type: object required: - id - url - kind - events - active - created_at - updated_at - project_id properties: id: type: string format: uuid url: type: string format: uri description: Webhook delivery endpoint kind: type: string enum: - kapso - meta default: kapso description: >- Webhook type - 'kapso' for event-based webhooks, 'meta' for raw Meta payload forwarding events: type: array description: >- Event subscriptions (required for 'kapso' webhooks, empty for 'meta') items: type: string active: type: boolean description: Pause deliveries without deleting created_at: type: string format: date-time updated_at: type: string format: date-time project_id: type: string format: uuid phone_number_id: type: - string - 'null' description: Meta phone number ID secret_key: type: - string - 'null' description: Secret for signing requests headers: type: - object - 'null' additionalProperties: true description: Custom request headers buffer_enabled: type: - boolean - 'null' description: Batch messages before delivery buffer_window_seconds: type: - integer - 'null' description: Seconds to wait before sending batch max_buffer_size: type: - integer - 'null' description: Max messages per batch buffer_events: type: array description: Events to buffer items: type: string inactivity_minutes: type: - integer - 'null' description: Trigger inactivity event after N minutes payload_version: type: - string - 'null' description: Webhook payload format version (defaults to 'v2') ErrorResponse: type: object required: - error properties: error: type: string responses: UnauthorizedError: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' PaymentRequiredError: description: Feature requires a paid plan content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFoundError: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ValidationError: description: Request validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key ````