Svix Webhooks AutoConfig API

openapi: 3.2.0
info:
  title: Svix Webhooks AutoConfig API
  description: Welcome to the Svix API documentation!
  version: 1.922.0
  x-logo:
    url: https://www.svix.com/static/img/brand-padded.svg
    altText: Svix Logo
servers:
- url: https://api.eu.svix.com
  description: The Svix EU region
- url: https://api.us.svix.com
  description: The Svix US region
- url: https://api.ca.svix.com
  description: The Svix Canada region
- url: https://api.au.svix.com
  description: The Svix Australia region
- url: https://api.in.svix.com
  description: The Svix India region
tags:
- name: Webhooks AutoConfig
paths:
  /api/v1/app/{app_id}/auto-config:
    post:
      tags:
      - Webhooks AutoConfig
      summary: Create Subscription
      description: Create a new auto-config flow (creates an endpoint awaiting configuration).
      operationId: v1.endpoint.auto-config.create
      parameters:
      - in: path
        name: app_id
        description: The Application's ID or UID.
        required: true
        schema:
          description: The Application's ID or UID.
          type: string
          maxLength: 256
          minLength: 1
          pattern: ^[a-zA-Z0-9\-_.]+$
          example: unique-identifier
        style: simple
      - in: header
        name: idempotency-key
        description: The request's idempotency key
        schema:
          type: string
        style: simple
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoConfigOut'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
      security:
      - HTTPBearer: []
      x-internal: true
  /api/v1/app/{app_id}/endpoint/{endpoint_id}/auto-config:
    get:
      tags:
      - Webhooks AutoConfig
      summary: Get Subscription
      description: Get the current auto-config token in censored form.
      operationId: v1.endpoint.auto-config.get
      parameters:
      - in: path
        name: app_id
        description: The Application's ID or UID.
        required: true
        schema:
          description: The Application's ID or UID.
          type: string
          maxLength: 256
          minLength: 1
          pattern: ^[a-zA-Z0-9\-_.]+$
          example: unique-identifier
        style: simple
      - in: path
        name: endpoint_id
        description: The Endpoint's ID or UID.
        required: true
        schema:
          description: The Endpoint's ID or UID.
          type: string
          maxLength: 256
          minLength: 1
          pattern: ^[a-zA-Z0-9\-_.]+$
          example: unique-identifier
        style: simple
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoConfigCensoredOut'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
      security:
      - HTTPBearer: []
      x-internal: true
    put:
      tags:
      - Webhooks AutoConfig
      summary: Update Subscription
      description: Update an auto-config endpoint by providing endpoint details.
      operationId: v1.endpoint.auto-config.update
      parameters:
      - in: path
        name: app_id
        description: The Application's ID or UID.
        required: true
        schema:
          description: The Application's ID or UID.
          type: string
          maxLength: 256
          minLength: 1
          pattern: ^[a-zA-Z0-9\-_.]+$
          example: unique-identifier
        style: simple
      - in: path
        name: endpoint_id
        description: The Endpoint's ID or UID.
        required: true
        schema:
          description: The Endpoint's ID or UID.
          type: string
          maxLength: 256
          minLength: 1
          pattern: ^[a-zA-Z0-9\-_.]+$
          example: unique-identifier
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscribeIn'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndpointOut'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
      security:
      - HTTPBearer: []
      x-internal: true
  /api/v1/app/{app_id}/endpoint/{endpoint_id}/auto-config/rotate:
    post:
      tags:
      - Webhooks AutoConfig
      summary: Rotate Subscription
      description: Rotate the auth token for an auto-config endpoint.
      operationId: v1.endpoint.auto-config.rotate
      parameters:
      - in: path
        name: app_id
        description: The Application's ID or UID.
        required: true
        schema:
          description: The Application's ID or UID.
          type: string
          maxLength: 256
          minLength: 1
          pattern: ^[a-zA-Z0-9\-_.]+$
          example: unique-identifier
        style: simple
      - in: path
        name: endpoint_id
        description: The Endpoint's ID or UID.
        required: true
        schema:
          description: The Endpoint's ID or UID.
          type: string
          maxLength: 256
          minLength: 1
          pattern: ^[a-zA-Z0-9\-_.]+$
          example: unique-identifier
        style: simple
      - in: header
        name: idempotency-key
        description: The request's idempotency key
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RotateSubscriptionIn'
        required: true
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoConfigOut'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorOut'
      security:
      - HTTPBearer: []
      x-internal: true
components:
  schemas:
    AutoConfigCensoredOut:
      type: object
      properties:
        updatedAt:
          type: string
          format: date-time
        tokenCensored:
          type: string
        endpId:
          description: The Endpoint's ID.
          type: string
          maxLength: 30
          minLength: 30
          pattern: ^ep_[A-Za-z0-9]{27}$
          example: ep_1srOrx2ZWZBpBUvZwXKQmoEYga2
      required:
      - endpId
      - tokenCensored
      - updatedAt
    AutoConfigSinkType:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - poller
          config:
            $ref: '#/components/schemas/SinkInCommon'
        required:
        - config
        - type
      - type: object
        properties:
          type:
            type: string
            enum:
            - http
          config:
            $ref: '#/components/schemas/EndpointIn'
        required:
        - config
        - type
    HttpErrorOut:
      title: HttpError
      type: object
      properties:
        code:
          type: string
        detail:
          type: string
      required:
      - code
      - detail
    AutoConfigOut:
      type: object
      properties:
        updatedAt:
          type: string
          format: date-time
        token:
          type: string
        endpId:
          description: The Endpoint's ID.
          type: string
          maxLength: 30
          minLength: 30
          pattern: ^ep_[A-Za-z0-9]{27}$
          example: ep_1srOrx2ZWZBpBUvZwXKQmoEYga2
      required:
      - endpId
      - token
      - updatedAt
    EndpointOut:
      type: object
      properties:
        id:
          description: The Endpoint's ID.
          type: string
          maxLength: 30
          minLength: 30
          pattern: ^ep_[A-Za-z0-9]{27}$
          example: ep_1srOrx2ZWZBpBUvZwXKQmoEYga2
        metadata:
          type: object
          additionalProperties:
            type: string
        url:
          type: string
          format: uri
          minLength: 1
          maxLength: 65536
          example: https://example.com/webhook/
        description:
          type: string
        rateLimit:
          description: Deprecated, use `throttleRate` instead.
          type: integer
          format: uint16
          deprecated: true
          minimum: 0
          nullable: true
        throttleRate:
          description: 'Maximum messages per second to send to this endpoint.


            Outgoing messages will be throttled to this rate.'
          type: integer
          format: uint16
          minimum: 0
          nullable: true
        uid:
          description: Optional unique identifier for the endpoint.
          type: string
          maxLength: 256
          minLength: 1
          pattern: ^[a-zA-Z0-9\-_.]+$
          example: unique-identifier
          nullable: true
        version:
          type: integer
          format: int32
          deprecated: true
          minimum: 1
          example: 1
        disabled:
          type: boolean
          default: false
          example: false
        filterTypes:
          type: array
          nullable: true
          items:
            description: The event type's name
            type: string
            maxLength: 256
            pattern: ^[a-zA-Z0-9\-_.]+$
            example: user.signup
          minItems: 1
          uniqueItems: true
          example:
          - user.signup
          - user.deleted
        channels:
          description: List of message channels this endpoint listens to (omit for all).
          type: array
          nullable: true
          items:
            type: string
            maxLength: 128
            pattern: ^[a-zA-Z0-9\-_.:+]+$
            example: project_1337
          maxItems: 10
          minItems: 1
          uniqueItems: true
          example:
          - project_123
          - group_2
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
      - createdAt
      - description
      - id
      - metadata
      - updatedAt
      - url
      - version
    EndpointIn:
      type: object
      properties:
        url:
          type: string
          format: uri
          minLength: 1
          maxLength: 65536
          example: https://example.com/webhook/
        description:
          type: string
          default: ''
          example: An example endpoint name
        rateLimit:
          description: Deprecated, use `throttleRate` instead.
          type: integer
          format: uint16
          deprecated: true
          minimum: 1
          nullable: true
        throttleRate:
          description: 'Maximum messages per second to send to this endpoint.


            Outgoing messages will be throttled to this rate.'
          type: integer
          format: uint16
          minimum: 1
          nullable: true
        uid:
          description: Optional unique identifier for the endpoint.
          type: string
          maxLength: 256
          minLength: 1
          pattern: ^[a-zA-Z0-9\-_.]+$
          example: unique-identifier
          nullable: true
        version:
          type: integer
          format: uint16
          default: 1
          deprecated: true
          nullable: true
          minimum: 1
          example: 1
        disabled:
          type: boolean
          default: false
          example: false
        filterTypes:
          type: array
          nullable: true
          items:
            description: The event type's name
            type: string
            maxLength: 256
            pattern: ^[a-zA-Z0-9\-_.]+$
            example: user.signup
          minItems: 1
          uniqueItems: true
          example:
          - user.signup
          - user.deleted
        channels:
          description: List of message channels this endpoint listens to (omit for all).
          type: array
          nullable: true
          items:
            type: string
            maxLength: 128
            pattern: ^[a-zA-Z0-9\-_.:+]+$
            example: project_1337
          maxItems: 10
          minItems: 1
          uniqueItems: true
          example:
          - project_123
          - group_2
        secret:
          description: 'The endpoint''s verification secret.


            Format: `base64` encoded random bytes optionally prefixed with `whsec_`.

            It is recommended to not set this and let the server generate the secret.'
          type: string
          pattern: ^(whsec_|whsk_|whsk1_|whpk_|whpk1_)?[a-zA-Z0-9+/=]{32,100}$
          example: whsec_C2FVsBQIhrscChlQIMV+b5sSYspob7oD
          nullable: true
        metadata:
          type: object
          default: {}
          additionalProperties:
            type: string
        headers:
          type: object
          nullable: true
          additionalProperties:
            type: string
          example:
            X-Example: '123'
            X-Foobar: Bar
      required:
      - url
    EndpointSecretRotateIn:
      type: object
      properties:
        key:
          description: 'The endpoint''s verification secret.


            Format: `base64` encoded random bytes optionally prefixed with `whsec_`.

            It is recommended to not set this and let the server generate the secret.'
          type: string
          default: null
          pattern: ^(whsec_|whsk_|whsk1_|whpk_|whpk1_)?[a-zA-Z0-9+/=]{32,100}$
          example: whsec_C2FVsBQIhrscChlQIMV+b5sSYspob7oD
          nullable: true
        gracePeriodSeconds:
          description: 'How long the old secret will be valid for, in seconds.


            Valid values are between 0 (immediate expiry) and 7 days. The default is 24 hours.'
          type: integer
          format: uint32
          default: 86400
          maximum: 604800
          minimum: 0
          nullable: true
    SinkInCommon:
      type: object
      properties:
        description:
          type: string
          default: ''
          example: An example endpoint name
        rateLimit:
          description: Deprecated, use `throttleRate` instead.
          type: integer
          format: uint16
          deprecated: true
          minimum: 1
          nullable: true
        throttleRate:
          description: 'Maximum messages per second to send to this endpoint.


            Outgoing messages will be throttled to this rate.'
          type: integer
          format: uint16
          minimum: 1
          nullable: true
        uid:
          description: Optional unique identifier for the sink.
          type: string
          maxLength: 256
          minLength: 1
          pattern: ^[a-zA-Z0-9\-_.]+$
          example: unique-identifier
          nullable: true
        secret:
          description: 'The endpoint''s verification secret.


            Format: `base64` encoded random bytes optionally prefixed with `whsec_`.

            It is recommended to not set this and let the server generate the secret.'
          type: string
          pattern: ^(whsec_|whsk_|whsk1_|whpk_|whpk1_)?[a-zA-Z0-9+/=]{32,100}$
          example: whsec_C2FVsBQIhrscChlQIMV+b5sSYspob7oD
          nullable: true
        disabled:
          type: boolean
          default: false
          example: false
        filterTypes:
          type: array
          nullable: true
          items:
            description: The event type's name
            type: string
            maxLength: 256
            pattern: ^[a-zA-Z0-9\-_.]+$
            example: user.signup
          minItems: 1
          uniqueItems: true
          example:
          - user.signup
          - user.deleted
        channels:
          description: List of message channels this sink listens to (omit for all).
          type: array
          nullable: true
          items:
            type: string
            maxLength: 128
            pattern: ^[a-zA-Z0-9\-_.:+]+$
            example: project_1337
          maxItems: 10
          minItems: 1
          uniqueItems: true
          example:
          - project_123
          - group_2
        metadata:
          type: object
          default: {}
          additionalProperties:
            type: string
    RotateSubscriptionIn:
      type: object
      properties:
        signingSecret:
          default: null
          $ref: '#/components/schemas/EndpointSecretRotateIn'
          nullable: true
    ValidationError:
      description: Validation errors have their own schema to provide context for invalid requests eg. mismatched types and out of bounds values. There may be any number of these per 422 UNPROCESSABLE ENTITY error.
      type: object
      properties:
        loc:
          description: The location as a [`Vec`] of [`String`]s -- often in the form `["body", "field_name"]`, `["query", "field_name"]`, etc. They may, however, be arbitrarily deep.
          type: array
          items:
            type: string
        msg:
          description: The message accompanying the validation error item.
          type: string
        type:
          description: The type of error, often "type_error" or "value_error", but sometimes with more context like as "value_error.number.not_ge"
          type: string
      required:
      - loc
      - msg
      - type
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
      required:
      - detail
    SubscribeIn:
      type: object
      properties:
        endpoint:
          $ref: '#/components/schemas/EndpointIn'
          nullable: true
        sink:
          $ref: '#/components/schemas/AutoConfigSinkType'
          nullable: true
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
      description: HTTP Bearer token passed in the `Authorization` header
x-tagGroups:
- name: General
  tags:
  - Background Task
  - Environment
- name: Dispatch
  tags:
  - Application
  - Event Type
  - Authentication
  - Endpoint
  - Message
  - Message Attempt
  - Integration
  - Connector
- name: Stream
  tags:
  - Stream
  - Sink
  - Event
  - Stream Event Type
  - Stream Authentication
- name: Ingest
  tags:
  - Ingest Source
  - Ingest Endpoint
- name: Operational Webhooks
  tags:
  - Webhook
  - Webhook Endpoint
- name: Statistics
  tags:
  - Statistics
- name: Utility
  tags:


# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/svix/refs/heads/main/openapi/svix-webhooks-autoconfig-api-openapi.yml