> ## Documentation Index
> Fetch the complete documentation index at: https://autumn-b9b4c0fb-dev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Webhook

> Creates a webhook: a URL Autumn sends the listed events to, in the environment of the calling key. You choose the `id`, and it can't be changed later. Returns the signing secret once, in this response — store it, it cannot be read back.

### Body Parameters

<DynamicParamField body="id" type="string" required>
  Your ID for the webhook: letters, digits, `-` and `_`. It can't be changed after creation.
</DynamicParamField>

<DynamicParamField body="url" type="string" required>
  The https URL Autumn sends events to. Localhost and private-network addresses are rejected; tunnels such as ngrok work.
</DynamicParamField>

<DynamicParamField body="events" type="('customer.products.updated' | 'customer.threshold_reached' | 'balances.usage_alert_triggered' | 'balances.limit_reached' | 'billing.auto_topup_failed' | 'billing.auto_topup_succeeded' | 'billing.updated' | 'invoice.finalized' | 'vercel.resources.deleted' | 'vercel.resources.provisioned' | 'vercel.resources.rotate_secrets' | 'vercel.webhooks.event')[]">
  The events sent to this webhook. Leave it out to send every event. `vercel.*` events can't be mixed with other events.
</DynamicParamField>

<DynamicParamField body="description" type="string">
  A note for your own reference.
</DynamicParamField>

<DynamicParamField body="disabled" type="boolean">
  When true, no events are sent to the webhook.
</DynamicParamField>

### Response

<DynamicResponseField name="id" type="string">
  The webhook's ID. Webhooks made in the dashboard show their `ep_…` ID.
</DynamicResponseField>

<DynamicResponseField name="url" type="string">
  The URL Autumn sends events to.
</DynamicResponseField>

<DynamicResponseField name="description" type="string | null">
  A note for your own reference.
</DynamicResponseField>

<DynamicResponseField name="events" type="string[]">
  The events sent to this webhook, as `WebhookEventType` names; a type newer than your client is returned as-is. Empty means the webhook receives every event.
</DynamicResponseField>

<DynamicResponseField name="disabled" type="boolean">
  When true, no events are sent to the webhook.
</DynamicResponseField>

<DynamicResponseField name="created_at" type="number">
  When the webhook was created, ms since epoch.
</DynamicResponseField>

<DynamicResponseField name="updated_at" type="number">
  When the webhook was last changed, ms since epoch.
</DynamicResponseField>

<DynamicResponseField name="secret" type="string">
  The webhook's signing secret. Shown once, here: store it before you discard the response.
</DynamicResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "billing",
    "url": "https://example.com/webhooks/autumn",
    "events": [
      "billing.updated",
      "invoice.finalized"
    ],
    "description": "Plan changes and invoices",
    "disabled": false,
    "created_at": 1781113864000,
    "updated_at": 1781113864000,
    "secret": "whsec_abc123"
  }
  ```
</ResponseExample>


## OpenAPI

````yaml openapi POST /v1/webhooks.create
openapi: 3.1.0
info:
  title: Autumn API
  version: 2.4.0
servers:
  - url: https://api.useautumn.com
    description: Production server
security:
  - secretKey: []
paths:
  /v1/webhooks.create:
    post:
      tags:
        - webhooks
      description: >-
        Creates a webhook: a URL Autumn sends the listed events to, in the
        environment of the calling key. You choose the `id`, and it can't be
        changed later. Returns the signing secret once, in this response — store
        it, it cannot be read back.
      operationId: createWebhook
      parameters:
        - name: x-api-version
          in: header
          required: true
          schema:
            type: string
            default: 2.4.0
          x-speakeasy-globals-hidden: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  minLength: 1
                  maxLength: 256
                  pattern: ^[a-zA-Z0-9_-]+$
                  description: >-
                    Your ID for the webhook: letters, digits, `-` and `_`. It
                    can't be changed after creation.
                url:
                  type: string
                  pattern: ^[Hh][Tt][Tt][Pp][Ss]:\/\/
                  description: >-
                    The https URL Autumn sends events to. Localhost and
                    private-network addresses are rejected; tunnels such as
                    ngrok work.
                events:
                  type: array
                  items:
                    enum:
                      - customer.products.updated
                      - customer.threshold_reached
                      - balances.usage_alert_triggered
                      - balances.limit_reached
                      - billing.auto_topup_failed
                      - billing.auto_topup_succeeded
                      - billing.updated
                      - invoice.finalized
                      - vercel.resources.deleted
                      - vercel.resources.provisioned
                      - vercel.resources.rotate_secrets
                      - vercel.webhooks.event
                    type: string
                    description: An event type the webhook receives.
                  description: >-
                    The events sent to this webhook. Leave it out to send every
                    event. `vercel.*` events can't be mixed with other events.
                  default: []
                description:
                  type: string
                  description: A note for your own reference.
                disabled:
                  type: boolean
                  description: When true, no events are sent to the webhook.
              required:
                - id
                - url
              title: CreateWebhookParams
              examples:
                - id: billing
                  url: https://example.com/webhooks/autumn
                  events:
                    - billing.updated
                    - invoice.finalized
                  description: Plan changes and invoices
            example:
              id: billing
              url: https://example.com/webhooks/autumn
              events:
                - billing.updated
                - invoice.finalized
              description: Plan changes and invoices
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: >-
                      The webhook's ID. Webhooks made in the dashboard show
                      their `ep_…` ID.
                  url:
                    type: string
                    description: The URL Autumn sends events to.
                  description:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: A note for your own reference.
                  events:
                    type: array
                    items:
                      type: string
                    description: >-
                      The events sent to this webhook, as `WebhookEventType`
                      names; a type newer than your client is returned as-is.
                      Empty means the webhook receives every event.
                  disabled:
                    type: boolean
                    description: When true, no events are sent to the webhook.
                  created_at:
                    type: number
                    description: When the webhook was created, ms since epoch.
                  updated_at:
                    type: number
                    description: When the webhook was last changed, ms since epoch.
                  secret:
                    type: string
                    description: >-
                      The webhook's signing secret. Shown once, here: store it
                      before you discard the response.
                    readOnly: true
                required:
                  - id
                  - url
                  - description
                  - events
                  - disabled
                  - created_at
                  - updated_at
                  - secret
                title: CreateWebhookResponse
                examples:
                  - id: billing
                    url: https://example.com/webhooks/autumn
                    events:
                      - billing.updated
                      - invoice.finalized
                    description: Plan changes and invoices
                    disabled: false
                    created_at: 1781113864000
                    updated_at: 1781113864000
                    secret: whsec_abc123
              example:
                id: billing
                url: https://example.com/webhooks/autumn
                events:
                  - billing.updated
                  - invoice.finalized
                description: Plan changes and invoices
                disabled: false
                created_at: 1781113864000
                updated_at: 1781113864000
                secret: whsec_abc123
      x-codeSamples:
        - lang: typescript
          label: Typescript (SDK)
          source: |-
            import { Autumn } from 'autumn-js'

            const autumn = new Autumn()

            const result = await autumn.webhooks.create({
              id: "billing",
              url: "https://example.com/webhooks/autumn",
              events: [
                "billing.updated",
                "invoice.finalized",
              ],
              description: "Plan changes and invoices",
            });
        - lang: python
          label: Python (SDK)
          source: |-
            from autumn_sdk import Autumn

            autumn = Autumn(secret_key="am_sk_test...")

            res = autumn.webhooks.create(
                id="billing",
                url="https://example.com/webhooks/autumn",
                events=[
                    "billing.updated",
                    "invoice.finalized",
                ],
                description="Plan changes and invoices",
            )
components:
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````