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

# Create subscription

> Registers a subscription — `PUSH` by default, or `PULL` — and returns your signing secret **once**.

**Store `webhook_secret` immediately.** It is shown only in this response; if you lose it your only option is to rotate.

For a PULL subscription, omit `target` and set `deliveryMode: "PULL"`. A PULL subscription never delivers anything — it authorises and configures the event feed. You may have one live PULL subscription per partner, and it requires the `events` permission.



## OpenAPI

````yaml api-reference/endl-webhooks-api.json POST /api/v0/webhooks/subscriptions
openapi: 3.1.0
info:
  title: Endl Webhooks API
  version: '0'
  description: >-
    Register where your events go, inspect what happened to each delivery, and
    read the PULL feed.


    Every endpoint returns the standard Endl response envelope and requires the
    `webhooks` permission — the PULL feed additionally requires `events`.
servers:
  - url: https://qa-api.endl.xyz
    description: QA
security:
  - apiKey: []
tags:
  - name: Subscriptions
    description: Register and manage the endpoints that receive your events.
  - name: Deliveries
    description: Inspect and retry individual delivery attempts.
  - name: Events
    description: Read events from the PULL feed.
paths:
  /api/v0/webhooks/subscriptions:
    post:
      tags:
        - Subscriptions
      summary: Create subscription
      description: >-
        Registers a subscription — `PUSH` by default, or `PULL` — and returns
        your signing secret **once**.


        **Store `webhook_secret` immediately.** It is shown only in this
        response; if you lose it your only option is to rotate.


        For a PULL subscription, omit `target` and set `deliveryMode: "PULL"`. A
        PULL subscription never delivers anything — it authorises and configures
        the event feed. You may have one live PULL subscription per partner, and
        it requires the `events` permission.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                deliveryMode:
                  type: string
                  enum:
                    - PUSH
                    - PULL
                  default: PUSH
                target:
                  type: string
                  maxLength: 512
                  description: >-
                    Required for `PUSH`; ignored for `PULL`. Must be an absolute
                    `https://` URL on a public host, using an allowed port, with
                    no embedded credentials.
                eventFilter:
                  type: array
                  items:
                    type: string
                  default:
                    - '*'
                schemaVersion:
                  type: string
                  default: '1.0'
            example:
              target: https://api.acme.com/webhooks/endl
              eventFilter:
                - payout.completed
                - payout.failed
      responses:
        '201':
          description: Created. This response carries the signing secret.
          content:
            application/json:
              example:
                code: 201
                message: Subscription created
                status: SUCCESS
                data:
                  id: 2b1e8f40-3c9a-4d21-9f7e-6a1c0b5d2e34
                  deliveryMode: PUSH
                  target: https://api.acme.com/webhooks/endl
                  eventFilter:
                    - payout.completed
                    - payout.failed
                  schemaVersion: '1.0'
                  status: ACTIVE
                  secretHint: whsec_…5RtBw
                  webhook_secret: whsec_k2p9Fa7QxVn3Jh05RtBw
                  createdOn: '2026-09-02T12:34:56.789Z'
                errors: []
        '400':
          description: >-
            Invalid or blocked target, `target` missing for PUSH, or missing
            permission.
        '401':
          description: Authentication failed.
        '409':
          description: >-
            Duplicate target, the active cap of 5 was reached, or a live PULL
            subscription already exists.
        '422':
          description: SQS or SSE delivery was requested.
        '503':
          description: Endl could not verify the credential right now. Retry with backoff.
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: API-KEY
      description: >-
        Your partner API key. Requires the `webhooks` permission, or `events`
        for the PULL feed.

````