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

# Update event subscription

Partially update an event subscription. Omitted fields keep their current value — only send the fields you want to change.

To change authentication, send the full `authentication` object; omit it entirely to leave authentication unchanged, or send `{"type": "NONE"}` to clear it.

### Pausing and resuming deliveries

Send `{"active": false}` to stop deliveries for a subscription, and `{"active": true}` to start them again. Pausing keeps the subscription's `id`, signing secret and delivery history intact, so you don't need to delete and recreate it — useful while you deploy a change to your endpoint or investigate a failure.

While a subscription is paused, events that occur are **not queued for later delivery**. You will not receive them after resuming, so re-sync any affected products with [List Products](https://partner.headout.com/docs/affiliate/v2/products/list.md) once you're back up.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --location --request PATCH 'https://www.headout.com/api/public/v2/event-subscriptions/whsub_01j9z8x7v6w5u4t3s2r1q0p9o8/' \
--header 'Headout-Auth: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "url": "https://your-domain.com/webhooks/headout/events-v2"
}'
```

```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "whsub_01j9z8x7v6w5u4t3s2r1q0p9o8",
  "url": "https://your-domain.com/webhooks/headout/events-v2",
  "eventTypes": ["product.listing_status_changed"],
  "description": "Production event subscription",
  "active": true,
  "createdAt": "2026-07-30T10:15:00Z",
  "updatedAt": "2026-07-30T11:02:00Z",
  "authentication": {
    "type": "AUTHORIZATION_HEADER",
    "valueHint": "oken"
  },
  "signingSecretHint": "B0eHyA"
}
```

```json 400 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "timestamp": 1786441790000,
  "traceId": "aad8e04d4cb6d466",
  "traceTokenOriginal": "E33C34A07812483E9DE02FF272F48A34",
  "error": {
    "code": "CAL-P0006",
    "message": "eventTypes contains an unrecognized value",
    "detailedMessage": "field=eventTypes"
  }
}
```

```json 404 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "timestamp": 1786441790000,
  "traceId": "aad8e04d4cb6d466",
  "traceTokenOriginal": "E33C34A07812483E9DE02FF272F48A34",
  "error": {
    "code": "CAL-P0008",
    "message": "No event subscription found for this ID"
  }
}
```


## OpenAPI

````yaml PATCH /api/public/v2/event-subscriptions/{id}/
openapi: 3.1.0
info:
  title: Headout API Docs - Common v2
  version: 0.0.1
servers:
  - url: https://www.headout.com
    description: Production server
  - url: https://www.sandbox-headout.com
    description: Sandbox server
security: []
paths:
  /api/public/v2/event-subscriptions/{id}/:
    patch:
      tags:
        - Event Subscriptions
      summary: Update event subscription
      operationId: v2UpdateEventSubscription
      parameters:
        - $ref: '#/components/parameters/eventSubscriptionId'
      requestBody:
        required: true
        description: Partial update — omitted fields keep their current value.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEventSubscriptionRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventSubscription'
        '400':
          description: >-
            Invalid `url`, an unrecognized value in `eventTypes`, or a malformed
            request body
        '404':
          description: No event subscription found for this ID
        '422':
          description: URL rejected for delivery-safety reasons
      security:
        - apiKeyAuth: []
components:
  parameters:
    eventSubscriptionId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: >-
        Identifier of the event subscription, e.g. `whsub_01j...`. Returned as
        `id` from Create event subscription and List event subscriptions.
  schemas:
    UpdateEventSubscriptionRequest:
      type: object
      properties:
        url:
          type: string
          format: uri
          pattern: ^https://.*
          description: >-
            HTTPS URL Headout will deliver events to. Omit to keep the current
            value.
        eventTypes:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/EventSubscriptionType'
          description: >-
            Event types to subscribe to. Omit to keep the current value; if
            present, must be non-empty with no duplicates.
        authentication:
          $ref: '#/components/schemas/EventSubscriptionAuthenticationRequest'
        description:
          type: string
          maxLength: 500
          description: Optional free-text label. Omit to keep the current value.
        active:
          type: boolean
          description: >-
            Pause or resume delivery. `false` stops deliveries for this
            subscription; `true` resumes them. Omit to keep the current value.
            Pausing keeps the subscription's `id`, signing secret and delivery
            history intact — you do not need to delete and recreate it.
    EventSubscription:
      type: object
      properties:
        id:
          type: string
          description: >-
            Identifier of this subscription, e.g. `whsub_01j...`. Use in
            Get/Update/Delete/Rotate secret.
        url:
          type: string
          description: HTTPS URL events are delivered to.
        eventTypes:
          type: array
          items:
            $ref: '#/components/schemas/EventSubscriptionType'
          description: Event types this subscription is subscribed to.
        description:
          type:
            - string
            - 'null'
          description: Free-text label for this subscription, if set.
        active:
          type: boolean
          description: Whether this subscription is currently active.
        createdAt:
          type: string
          format: date-time
          description: When this subscription was created.
        updatedAt:
          type: string
          format: date-time
          description: When this subscription was last updated.
        authentication:
          $ref: '#/components/schemas/EventSubscriptionAuthentication'
        signingSecret:
          type:
            - string
            - 'null'
          description: >-
            Signing secret for this subscription, used to verify the
            `X-Headout-Signature` header on delivered events. Only present in
            the response to Create event subscription and Rotate signing secret
            — never returned again afterwards, so store it immediately.
        signingSecretHint:
          type:
            - string
            - 'null'
          description: >-
            Masked trailing characters of the current signing secret, returned
            on reads so you can tell which secret is active without exposing it.
    EventSubscriptionType:
      type: string
      enum:
        - product.listing_status_changed
        - product.variant_listing_status_changed
        - product.data_changed
        - product.variant_pricing_changed
      description: >
        The event types available for subscription:

        - `product.listing_status_changed` — A product was listed or unlisted.

        - `product.variant_listing_status_changed` — One or more variants under
        a product were listed or unlisted. Fires when a product is listed (its
        variants arrive as listed) or delisted (all its variants are reported
        delisted), and also while a product stays listed but individual variants
        under it are listed or delisted.

        - `product.data_changed` — The content of a product that is listed (and
        was listed at the previous sync) changed. `data.changedFields` names
        which fields differ. Listing/unlisting and variant add/remove are
        reported by the two events above, not here.

        - `product.variant_pricing_changed` — The near-term pricing of a variant
        under a listed product changed for a specific date. `data` names the
        `productId`, `variantId`, and `date` whose price moved, not the new
        amounts — re-fetch the price to read them.
    EventSubscriptionAuthenticationRequest:
      type: object
      required:
        - type
      description: >
        Authentication Headout attaches to webhook deliveries for this
        subscription. Tri-state on update: omit this field entirely to keep the
        current authentication unchanged, send `{"type": "NONE"}` to clear it,
        or send `{"type": "AUTHORIZATION_HEADER", "value": "..."}` to set it.
      properties:
        type:
          type: string
          enum:
            - NONE
            - AUTHORIZATION_HEADER
          description: >-
            `NONE` sends no authentication header. `AUTHORIZATION_HEADER` sends
            `value` as the `Authorization` header on every delivery.
        value:
          type: string
          minLength: 6
          maxLength: 1024
          description: >-
            Required when `type` is `AUTHORIZATION_HEADER`. Sent verbatim as the
            `Authorization` header on every delivery attempt, including retries.
            Must be 6–1024 characters and free of control characters. Not echoed
            back in any response — only a masked `valueHint` is returned.
    EventSubscriptionAuthentication:
      type: object
      properties:
        type:
          type: string
          enum:
            - NONE
            - AUTHORIZATION_HEADER
          description: Authentication type configured for this subscription.
        valueHint:
          type:
            - string
            - 'null'
          description: >-
            Masked trailing characters of the configured `Authorization` header
            value. Only present when `type` is `AUTHORIZATION_HEADER`. The full
            value is never returned.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Headout-Auth

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.