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

# Create a webhook subscription

> Subscribes a callback URL to a webhook event type. Use `GET /events` to discover valid `event_name` values.



## OpenAPI

````yaml /api-reference/openapi.json post /events/subscription
openapi: 3.1.0
info:
  title: Karat Payout API
  description: >-
    Your gateway to seamless, automated, and scalable payment solutions. The
    Karat Payout API lets you create recipients, send payouts, track payment
    status, manage tax documents, record external payments, and subscribe to
    webhook events.
  version: 1.0.0
servers:
  - url: https://payouts.api.trykarat.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Payments
    description: Create and manage outgoing payouts to recipients.
  - name: Recipients
    description: Manage the payees you send payouts to.
  - name: Tax
    description: Retrieve recipient tax forms (W-9) and download links.
  - name: External Payments
    description: Record and manage payments made outside of Karat.
  - name: Webhooks
    description: Subscribe to event notifications for payout activity.
paths:
  /events/subscription:
    post:
      tags:
        - Webhooks
      summary: Create a webhook subscription
      description: >-
        Subscribes a callback URL to a webhook event type. Use `GET /events` to
        discover valid `event_name` values.
      operationId: createWebhookSubscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - event_name
                - callback_url
              properties:
                event_name:
                  type: string
                  description: The event type to subscribe to, e.g. `payout.updated`.
                callback_url:
                  type: string
                  format: uri
                  description: The URL to deliver events to.
            example:
              event_name: payout.updated
              callback_url: https://example.com/api/webhooks/callback
      responses:
        '201':
          description: The subscription was created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      subscription:
                        $ref: '#/components/schemas/WebhookSubscription'
                      secret:
                        type: string
                        description: >-
                          Signing secret for verifying deliveries from this
                          subscription. Store it securely.
              example:
                data:
                  subscription:
                    id: 50fe99c8-6412-4557-91c8-c9d112dadbc7
                    eventName: payout.updated
                    callbackUrl: https://example.com/api/webhooks/callback
                    createdAt: '2026-03-03T21:17:52.77594+00:00'
                  secret: example_secret
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    WebhookSubscription:
      type: object
      properties:
        id:
          type: string
          format: uuid
        eventName:
          type: string
          example: payout.updated
        callbackUrl:
          type: string
          format: uri
        createdAt:
          type: string
          format: date-time
        lastSentAt:
          type: string
          format: date-time
          nullable: true
    Error:
      type: object
      description: Standard error envelope returned for all non-2xx responses.
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: string
          required:
            - message
      required:
        - error
  responses:
    BadRequest:
      description: The request was invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: 'amount: amount must be positive'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: Invalid api key
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Pass your API key as a bearer token: `Authorization: Bearer <API_KEY>`.'

````