> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tikk.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a webhook

> Starts sending the events you pick to `url`. See
[Webhooks](/api-reference/webhooks) for the payload, the signature and
retries.

For an API key the response includes `signing_secret`, the secret this
webhook's deliveries are signed with. It's only returned here: store it
now. For a partner app, deliveries are signed with the app's secret
from the developer portal instead.

The URL must use HTTPS and resolve only to public addresses. A
credential can have up to 10 webhooks, one per URL.

**Scopes:** `webhooks.write` and `bookings.read` · **Plan:** Pro




## OpenAPI

````yaml api-reference/openapi.yaml POST /webhooks
openapi: 3.1.0
info:
  title: Tikk API
  version: 1.0.0
  summary: Your Tikk profile, services, free time slots and bookings.
  description: |
    A REST API over one Tikk account: its public profile, its services, the
    time slots it has free and the bookings people have made with it. Reading
    is the default; writing is limited to services and webhooks.

    Every response is JSON, every timestamp is ISO 8601 in UTC, and every
    request needs a bearer token: an API key (`tikk_sk_...`) or an OAuth access
    token. Each endpoint requires one scope. Rate limit: 60 requests per minute
    per credential.
  contact:
    name: Tikk support
    url: https://tikk.chat
servers:
  - url: https://app.tikk.chat/api/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Profile
    description: Your public profile and plan.
  - name: Services
    description: Your default services and single-use links.
  - name: Availability
    description: The time slots you have free.
  - name: Bookings
    description: The bookings people have made with you.
  - name: Webhooks
    description: URLs that receive your booking updates as they happen (Pro).
paths:
  /webhooks:
    post:
      tags:
        - Webhooks
      summary: Create a webhook
      description: |
        Starts sending the events you pick to `url`. See
        [Webhooks](/api-reference/webhooks) for the payload, the signature and
        retries.

        For an API key the response includes `signing_secret`, the secret this
        webhook's deliveries are signed with. It's only returned here: store it
        now. For a partner app, deliveries are signed with the app's secret
        from the developer portal instead.

        The URL must use HTTPS and resolve only to public addresses. A
        credential can have up to 10 webhooks, one per URL.

        **Scopes:** `webhooks.write` and `bookings.read` · **Plan:** Pro
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookSubscription'
            example:
              url: https://yourapp.com/tikk/webhooks
              events:
                - booking.confirmed
                - booking.cancelled
      responses:
        '201':
          description: The new webhook, with its signing secret for API keys.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscriptionEnvelope'
              examples:
                apiKey:
                  summary: Created with an API key
                  value:
                    data:
                      id: 1830219341
                      url: https://yourapp.com/tikk/webhooks
                      events:
                        - booking.confirmed
                        - booking.cancelled
                      status: active
                      disabled_reason: null
                      consecutive_failures: 0
                      signing_secret_source: subscription
                      signing_secret: tikk_whsec_4f8Kd02LmQx7Rz1VbN6cT9yHs3Ue5Wa
                      last_success_at: null
                      last_failure_at: null
                      created_at: '2026-10-01T09:00:00+00:00'
                      updated_at: '2026-10-01T09:00:00+00:00'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ProForbidden'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - bearerAuth:
            - webhooks.write
            - bookings.read
components:
  schemas:
    CreateWebhookSubscription:
      type: object
      properties:
        url:
          type: string
          format: uri
          maxLength: 2048
          description: >-
            HTTPS, resolving only to public addresses. No credentials or
            fragment.
        events:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/WebhookEventType'
      required:
        - url
        - events
    WebhookSubscriptionEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/WebhookSubscription'
      required:
        - data
    WebhookEventType:
      type: string
      enum:
        - booking.requested
        - booking.confirmed
        - booking.declined
        - booking.cancelled
        - booking.rescheduled
    WebhookSubscription:
      type: object
      properties:
        id:
          type: integer
          example: 1830219341
        url:
          type: string
          format: uri
          example: https://yourapp.com/tikk/webhooks
        events:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEventType'
        status:
          type: string
          enum:
            - active
            - disabled
        disabled_reason:
          type:
            - string
            - 'null'
          enum:
            - manual
            - failing
            - gone
            - null
          description: |
            Why the webhook is off: `manual` (switched off with `PATCH`),
            `failing` (5 events in a row failed for good) or `gone` (your
            endpoint answered `410`).
        consecutive_failures:
          type: integer
          description: Events in a row that failed for good. Resets on any success.
          example: 0
        signing_secret_source:
          type: string
          enum:
            - subscription
            - app
          description: >
            `subscription`: deliveries are signed with the `signing_secret`

            returned when this webhook was created (API keys). `app`: signed
            with

            your app's secret from the developer portal (partner apps).
        signing_secret:
          type: string
          description: Only in the `POST /webhooks` response, and only for API keys.
          example: tikk_whsec_4f8Kd02LmQx7Rz1VbN6cT9yHs3Ue5Wa
        last_success_at:
          type:
            - string
            - 'null'
          format: date-time
        last_failure_at:
          type:
            - string
            - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - url
        - events
        - status
        - disabled_reason
        - consecutive_failures
        - signing_secret_source
        - last_success_at
        - last_failure_at
        - created_at
        - updated_at
    Error:
      type: object
      properties:
        message:
          type: string
          description: What went wrong. Branch on the status code, not on this text.
      required:
        - message
    MissingScopeError:
      type: object
      properties:
        message:
          type: string
          example: Missing required scope.
        scopes:
          type: array
          description: The scope or scopes the endpoint needs.
          items:
            type: string
      required:
        - message
        - scopes
    PlanRequiredError:
      type: object
      properties:
        message:
          type: string
        error:
          type: string
          const: plan_required
        required_plan:
          type: string
          const: pro
        upgrade_url:
          type: string
          format: uri
          description: Where the account owner can upgrade.
      required:
        - message
        - error
        - required_plan
        - upgrade_url
    ValidationError:
      type: object
      properties:
        message:
          type: string
          example: The to field must be a date after or equal to from.
        errors:
          type: object
          description: Failed rules, keyed by parameter name.
          additionalProperties:
            type: array
            items:
              type: string
          example:
            to:
              - The to field must be a date after or equal to from.
      required:
        - message
        - errors
  responses:
    Unauthorized:
      description: No credential was sent, or it's revoked, expired or unknown.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Unauthenticated.
    ProForbidden:
      description: |
        The credential doesn't carry a scope this endpoint needs, or the
        account is on Free and webhooks need Pro (`plan_required`).
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/MissingScopeError'
              - $ref: '#/components/schemas/PlanRequiredError'
          examples:
            missingScope:
              summary: Missing scope
              value:
                message: Missing required scope.
                scopes:
                  - webhooks.write
            planRequired:
              summary: Account on Free
              value:
                message: This endpoint requires the Tikk account to be on the Pro plan.
                error: plan_required
                required_plan: pro
                upgrade_url: https://app.tikk.chat/billing
    ValidationFailed:
      description: One or more parameters failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
    TooManyRequests:
      description: More than 60 requests in a minute for this credential.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Too Many Attempts.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        An API key from **Settings → API Keys** (starts with `tikk_sk_`), or an
        OAuth access token for a partner app. Both carry scopes; each endpoint
        lists the one it needs.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.