> ## Documentation Index > Fetch the complete documentation index at: https://developer.zeeg.me/llms.txt > Use this file to discover all available pages before exploring further. # Create Webhook Subscription > Register a webhook callback URL to receive real-time notifications for selected Zeeg events such as bookings, cancellations, and reschedules. ## OpenAPI ````yaml POST /webhooks openapi: 3.0.0 info: title: Zeeg Public API description: >- Zeeg public API documentation. ## Authentication All endpoints require a Bearer token. You can generate an API token from [your Zeeg dashboard](https://app.zeeg.me/account/settings/api-access). Each token is scoped to specific permissions (e.g. `events:read`, `webhooks:write`). Make sure your token has the required scopes for the endpoints you want to use. ## Recommended Headers We recommend including the `Accept: application/json` header in all API requests to ensure you receive JSON responses. version: 2.0.0 x-logo: url: https://app.zeeg.me/img/logo-dark.2ca83593.svg backgroundColor: '#f7f7f9' altText: zeeg contact: name: Zeeg Support email: support@zeeg.me url: https://zeeg.me/en/contact license: name: Proprietary url: https://zeeg.me/en/legal/terms termsOfService: https://zeeg.me/en/legal/terms servers: - url: https://api.zeeg.me/v2 description: Production security: - bearer: [] tags: - name: Scheduled Events description: Management of events scheduled via Zeeg - name: Scheduling Pages description: Scheduling pages information and management - name: Availability Schedule description: Read and change availability for users - name: Webhooks description: Webhooks management - name: Notes description: Notes for scheduled events - name: Workspaces & Teams description: Workspace users and team member management - name: AI Agent description: AI Agent integration endpoints - name: Payloads description: Webhook payload schemas - name: CRM - Objects description: >- Discover the schema of CRM objects (standard and custom) including all attribute definitions - name: CRM - Companies description: Create, read, update, and delete CRM company records - name: CRM - People description: Create, read, update, and delete CRM person records paths: /webhooks: parameters: [] post: tags: - Webhooks summary: Create webhook subscription description: > Creates a new webhook subscription. When an event matching your subscription occurs, Zeeg will send a POST request to the specified `callbackUrl` with the event payload. You can view and manage your webhook subscriptions from the [Zeeg dashboard](https://app.zeeg.me/account/settings/webhooks). **Scope:** Set up a webhook subscription for either the whole organization or a specific user: - `user`: The webhook fires only for events belonging to the authenticated user. - `organization`: The webhook fires for events belonging to any member of the authenticated user's organization. Requires an organization admin/owner token. **Token:** You can optionally provide a `token` string that will be included in the webhook payload headers. Use this to verify that incoming webhook requests originate from Zeeg. **Pre-creation test event:** Before the webhook is persisted, Zeeg sends a synthetic test event to your `callbackUrl`. The webhook is only created if your endpoint returns a 2xx response. On success, the response is `201` with the new resource and a `testResult` field. On failure, the response is `424 Failed Dependency` with `resource: null` and a `testResult` describing what went wrong — no webhook exists, so fix your endpoint and re-issue the request. operationId: post-webhooks requestBody: content: application/json: schema: type: object required: - callbackUrl - events - scope properties: callbackUrl: type: string format: uri description: >- The URL that Zeeg will send webhook payloads to. Must be a valid HTTPS URL. events: type: array description: List of event types to subscribe to. items: type: string enum: - invitee.scheduled - invitee.cancelled - routing_form.submitted - ai_agent.call_completed scope: type: string enum: - user - organization description: >- The scope of the webhook subscription. Use `user` for personal webhooks or `organization` for organization-wide webhooks. token: type: string minLength: 8 maxLength: 1000 pattern: ^[\x21-\x7E]+$ description: >- Optional verification token. When set, Zeeg includes it in a `Token` header on every webhook delivery (including the test endpoint). Use it to verify that incoming requests originate from Zeeg. Must be at least 8 characters and contain only printable, non-whitespace ASCII characters. Leading and trailing whitespace are trimmed automatically. examples: User-scoped webhook: value: callbackUrl: https://example.com/webhooks/zeeg events: - invitee.scheduled - invitee.cancelled scope: user token: my-secret-token-123 Organization-scoped webhook: value: callbackUrl: https://example.com/webhooks/zeeg-org events: - invitee.scheduled - invitee.cancelled - routing_form.submitted scope: organization responses: '201': description: Created content: application/json: schema: type: object properties: success: type: boolean resource: type: object description: The created webhook. properties: uuid: type: string format: uuid name: type: string nullable: true description: type: string nullable: true callbackUrl: type: string format: uri scope: type: string enum: - user - organization creator: type: object properties: firstName: type: string lastName: type: string slug: type: string events: type: array items: type: string organization: type: string format: uri nullable: true apiVersion: type: string nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time testResult: type: object nullable: true description: >- Result of the synthetic test event sent to the `callbackUrl`. `null` only when the test was skipped (rare). properties: delivered: type: boolean description: >- Whether the callback URL responded with a 2xx status. Always `true` on a `201` response. statusCode: type: integer nullable: true description: >- HTTP status code returned by the callback URL, or `null` if the request never reached it. error: type: string nullable: true enum: - connection_failed - request_failed description: >- Reason the request did not reach the callback URL. Only set when `delivered` is `false` and `statusCode` is `null`. examples: Webhook created and test delivered: value: success: true resource: uuid: 9a39bf60-a6c3-45e7-80cd-2cd36e520861 name: null description: null callbackUrl: https://example.com/webhooks/zeeg scope: user creator: firstName: Lena lastName: Meier slug: lena-meier events: - invitee.scheduled - invitee.cancelled organization: null apiVersion: null createdAt: '2026-04-10T08:30:00.000000Z' updatedAt: '2026-04-10T08:30:00.000000Z' testResult: delivered: true statusCode: 200 error: null '400': description: Bad Request content: application/json: schema: type: object properties: success: type: boolean message: type: string status: type: integer examples: Invalid request: value: success: false message: The request is invalid. status: 400 '401': $ref: '#/components/responses/401' '422': description: Unprocessable Entity content: application/json: schema: type: object properties: message: type: string errors: type: object properties: events: type: array items: type: string examples: Missing events: value: message: The events field is required. errors: events: - The events field is required. '424': description: >- Failed Dependency. The synthetic test event sent to your `callbackUrl` did not deliver, so the webhook was not created. Inspect `testResult` to see whether the callback responded with a non-2xx status (`statusCode`) or could not be reached at all (`error`). Fix your endpoint and re-issue the request. content: application/json: schema: type: object properties: success: type: boolean status: type: integer resource: type: object nullable: true testResult: type: object properties: delivered: type: boolean statusCode: type: integer nullable: true error: type: string nullable: true enum: - connection_failed - request_failed examples: Test rejected: value: success: false status: 424 resource: null testResult: delivered: false statusCode: 500 error: null Endpoint unreachable: value: success: false status: 424 resource: null testResult: delivered: false statusCode: null error: connection_failed security: - bearer: [] components: responses: '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string example: Unauthenticated. examples: Unauthenticated: value: message: Unauthenticated. securitySchemes: bearer: type: http scheme: bearer description: '' ````