> ## 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.

# Sync Webhooks

> Makes the listed webhooks exist as described: creates missing ones and updates ones that differ. Webhooks not listed are left alone, unless `skip_deletions` is false: then every webhook not listed is deleted, including ones made in the dashboard. Returns the signing secret of each webhook it created, once. Each webhook is applied on its own: failures are listed in `errors` while the rest still apply, and the request fails only when none could be applied.

### Body Parameters

<DynamicParamField body="webhooks" type="object[]" required>
  The webhooks to create or update. Webhooks not listed are left alone unless `skip_deletions` is false.

  <Expandable title="properties">
    <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>
  </Expandable>
</DynamicParamField>

<DynamicParamField body="skip_deletions" type="boolean">
  When false, `webhooks` is the environment's complete set: every webhook not listed is deleted, including ones made in the dashboard. Defaults true, which leaves unlisted webhooks alone.
</DynamicParamField>

### Response

<DynamicResponseField name="webhooks" type="object[]">
  The listed webhooks as they stand after the sync, except those in `errors`.

  <Expandable title="properties">
    <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>
  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="secrets" type="object[]">
  Signing secrets for the webhooks this sync created, shown once. Existing webhooks keep theirs.

  <Expandable title="properties">
    <DynamicResponseField name="id" type="string" />

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

<DynamicResponseField name="errors" type="object[]">
  Webhooks that couldn't be created, updated or deleted. The others were still applied; the request fails only when none could be.

  <Expandable title="properties">
    <DynamicResponseField name="id" type="string" />

    <DynamicResponseField name="message" type="string" />
  </Expandable>
</DynamicResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "webhooks": [
      {
        "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
      }
    ],
    "secrets": [
      {
        "id": "billing",
        "secret": "whsec_abc123"
      }
    ],
    "errors": []
  }
  ```
</ResponseExample>


## OpenAPI

````yaml openapi POST /v1/webhooks.sync
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.sync:
    post:
      tags:
        - webhooks
      description: >-
        Makes the listed webhooks exist as described: creates missing ones and
        updates ones that differ. Webhooks not listed are left alone, unless
        `skip_deletions` is false: then every webhook not listed is deleted,
        including ones made in the dashboard. Returns the signing secret of each
        webhook it created, once. Each webhook is applied on its own: failures
        are listed in `errors` while the rest still apply, and the request fails
        only when none could be applied.
      operationId: syncWebhooks
      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:
                webhooks:
                  type: array
                  items:
                    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
                  description: >-
                    The webhooks to create or update. Webhooks not listed are
                    left alone unless `skip_deletions` is false.
                skip_deletions:
                  type: boolean
                  default: true
                  description: >-
                    When false, `webhooks` is the environment's complete set:
                    every webhook not listed is deleted, including ones made in
                    the dashboard. Defaults true, which leaves unlisted webhooks
                    alone.
              required:
                - webhooks
              title: SyncWebhooksParams
              examples:
                - webhooks:
                    - id: billing
                      url: https://example.com/webhooks/autumn
                      events:
                        - billing.updated
                        - invoice.finalized
                      description: Plan changes and invoices
            example:
              webhooks:
                - 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:
                  webhooks:
                    type: array
                    items:
                      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.
                      required:
                        - id
                        - url
                        - description
                        - events
                        - disabled
                        - created_at
                        - updated_at
                    description: >-
                      The listed webhooks as they stand after the sync, except
                      those in `errors`.
                  secrets:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        secret:
                          type: string
                          description: >-
                            The webhook's signing secret. Shown once, here:
                            store it before you discard the response.
                          readOnly: true
                      required:
                        - id
                        - secret
                    description: >-
                      Signing secrets for the webhooks this sync created, shown
                      once. Existing webhooks keep theirs.
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        message:
                          type: string
                      required:
                        - id
                        - message
                    description: >-
                      Webhooks that couldn't be created, updated or deleted. The
                      others were still applied; the request fails only when
                      none could be.
                required:
                  - webhooks
                  - secrets
                  - errors
                title: SyncWebhooksResponse
                examples:
                  - webhooks:
                      - 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
                    secrets:
                      - id: billing
                        secret: whsec_abc123
                    errors: []
              example:
                webhooks:
                  - 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
                secrets:
                  - id: billing
                    secret: whsec_abc123
                errors: []
      x-codeSamples:
        - lang: typescript
          label: Typescript (SDK)
          source: |-
            import { Autumn } from 'autumn-js'

            const autumn = new Autumn()

            const result = await autumn.webhooks.sync({
              webhooks: [
                {
                  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.sync(
                webhooks=[
                    {
                        "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

````