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

# Create a new webhook on a given plan



## OpenAPI

````yaml /openapi.yaml post /plans/{planId}/webhooks
openapi: 3.0.3
info:
  title: Kardinal Builder API
  version: 1.0.0
  description: >
    This document specifies the REST API of Kardinal for builder users.


    Every endpoint applies to the single agency carried by the access token
    (either the sandbox

    agency or the production agency), which is why no agency id appears in the
    paths. An access

    token that does not grant access to exactly one agency is rejected with a
    `403`.
  contact:
    url: https://kardinal.ai/
    email: contact@kardinal.ai
servers:
  - url: /api/v2
security:
  - access_token: []
tags:
  - name: Plan
    description: How to create, retrieve, update and delete plans.
  - name: Solution
    description: How to retrieve the solution of a plan and its objectives.
  - name: Webhook
    description: How to create, retrieve, update and delete webhooks on a plan.
paths:
  /plans/{planId}/webhooks:
    parameters:
      - $ref: '#/components/parameters/planId'
    post:
      tags:
        - Webhook
      summary: Create a new webhook on a given plan
      operationId: postPlanWebhook
      requestBody:
        description: The webhook for creation.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
      responses:
        '201':
          description: The created webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopedPlanWebhook'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/NotAuthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    planId:
      name: planId
      description: The plan UUID.
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
  schemas:
    WebhookCreate:
      type: object
      properties:
        url:
          type: string
          description: The secure webhook URL (must be https).
          example: https://mydomain.com/webhooks
          format: uri
        headers:
          type: object
          description: A map of header key-value pairs.
          additionalProperties:
            type: string
          example:
            Authorization: Bearer your_token
            X-Custom-Header: custom_value
        withPlan:
          type: boolean
          description: >-
            Specifies whether we should also provide the plan in the webhook's
            payload.
          example: true
          default: false
        ttl:
          type: string
          description: |
            Defines the webhook's time to live in iso 8601 duration format.
            The value should be at least 30 minutes and at most 14 days.
          pattern: ^P(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(\d+H)?(\d+M)?(\d+S)?)?$
          example: PT1H
          default: PT30M
      required:
        - url
    EnvelopedPlanWebhook:
      type: object
      properties:
        item:
          $ref: '#/components/schemas/PlanWebhook'
        agencyId:
          $ref: '#/components/schemas/AgencyId'
        planId:
          $ref: '#/components/schemas/PlanId'
    UUID:
      type: string
      format: uuid
      description: Universally Unique Identifier.
      pattern: >-
        ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
      example: cd4ce4e3-0208-4b10-b346-25f235214e4f
      readOnly: true
    PlanWebhook:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        agencyId:
          $ref: '#/components/schemas/AgencyId'
        planId:
          $ref: '#/components/schemas/PlanId'
        url:
          type: string
          description: The secure webhook URL (must be https).
          example: https://mydomain.com/webhooks
          format: uri
        headers:
          type: object
          description: A map of header key-value pairs.
          additionalProperties:
            type: string
          example:
            Authorization: Bearer your_token
            X-Custom-Header: custom_value
        withPlan:
          type: boolean
          description: >-
            Specifies whether we should also provide the plan in the webhook's
            payload.
          example: true
          default: false
        active:
          type: boolean
          description: Specifies whether the webhook is active or not.
          example: false
          default: true
        createdAt:
          description: The webhook's creation date.
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/DateTime'
        updatedAt:
          description: The webhook's last update date.
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/DateTime'
        expiresAt:
          description: The webhook's expiration date.
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/DateTime'
    AgencyId:
      type: string
      description: The agency id.
      readOnly: true
      pattern: ^BLD[0-9]{7}_[a-zA-Z0-9-._~:@!$,]+$
      example: BLD1234567_production
    PlanId:
      description: The plan id.
      readOnly: true
      example: 4cbd0ab8-282c-4b30-b981-29e1ed8a2016
      allOf:
        - $ref: '#/components/schemas/UUID'
    EnvelopedErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    DateTime:
      type: string
      description: >-
        A full calendar date time, expressed in the ISO8601 **date** format:
        YYYY-MM-DDThh:mm:ssZ.
      example: '2019-11-15T12:34:56Z'
    Error:
      type: object
      readOnly: true
      properties:
        code:
          type: string
        message:
          type: string
        properties:
          $ref: '#/components/schemas/ErrorProperties'
      required:
        - message
        - code
    ErrorProperties:
      type: object
      additionalProperties:
        type: string
  responses:
    BadRequest:
      description: >-
        The server could not understand the request due to invalid content (bad
        syntax, bad format, bad values, etc).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnvelopedErrors'
    NotAuthenticated:
      description: The caller is not authenticated.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnvelopedErrors'
    Forbidden:
      description: The caller is not allowed to perform this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnvelopedErrors'
    InternalServerError:
      description: An internal server error has occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnvelopedErrors'
  securitySchemes:
    access_token:
      type: http
      scheme: bearer
      bearerFormat: JWT

````