openapi: 3.2.0
info:
  title: Shopify Admin REST Webhooks API
  description: The Shopify Admin REST API lets you build apps and integrations that extend and enhance the Shopify admin. Access products, customers, orders, inventory, fulfillment, and more. Endpoints are organized by resource type and versioned by release date.
  version: 2025-01
  contact:
    name: Shopify
    url: https://shopify.dev/docs/api/admin-rest
    email: api@shopify.com
  license:
    name: Shopify API Terms
    url: https://www.shopify.com/legal/api-terms
  x-date: '2026-03-04'
servers:
- url: https://{store}.myshopify.com/admin/api/2025-01
  description: Shopify Admin REST API
  variables:
    store:
      default: my-store
      description: The Shopify store subdomain
security:
- AccessToken: []
tags:
- name: Webhooks
  description: Manage webhook subscriptions
paths:
  /webhooks.json:
    get:
      operationId: listWebhooks
      summary: Shopify Retrieve a list of webhooks
      description: Retrieves a list of webhook subscriptions for the app.
      tags:
      - Webhooks
      parameters:
      - name: topic
        in: query
        description: Filter by webhook topic
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of results (max 250, default 50)
        schema:
          type: integer
          default: 50
          maximum: 250
      - name: since_id
        in: query
        description: Return webhooks after the specified ID
        schema:
          type: integer
      - name: fields
        in: query
        description: Comma-separated list of fields to include
        schema:
          type: string
      responses:
        '200':
          description: A list of webhooks
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhooks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
    post:
      operationId: createWebhook
      summary: Shopify Create a webhook subscription
      description: Creates a new webhook subscription. When the specified event occurs Shopify sends an HTTP POST to the provided address.
      tags:
      - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - webhook
              properties:
                webhook:
                  $ref: '#/components/schemas/WebhookInput'
      responses:
        '201':
          description: The created webhook
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhook:
                    $ref: '#/components/schemas/Webhook'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /webhooks/count.json:
    get:
      operationId: getWebhookCount
      summary: Shopify Retrieve a count of webhooks
      description: Retrieves a count of existing webhook subscriptions.
      tags:
      - Webhooks
      parameters:
      - name: topic
        in: query
        description: Count webhooks for a specific topic
        schema:
          type: string
      responses:
        '200':
          description: The webhook count
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
  /webhooks/{webhook_id}.json:
    get:
      operationId: getWebhook
      summary: Shopify Retrieve a single webhook
      description: Retrieves a single webhook subscription by ID.
      tags:
      - Webhooks
      parameters:
      - name: webhook_id
        in: path
        required: true
        description: The ID of the webhook
        schema:
          type: integer
      responses:
        '200':
          description: The requested webhook
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhook:
                    $ref: '#/components/schemas/Webhook'
    put:
      operationId: updateWebhook
      summary: Shopify Update a webhook subscription
      description: Updates an existing webhook subscription.
      tags:
      - Webhooks
      parameters:
      - name: webhook_id
        in: path
        required: true
        description: The ID of the webhook
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - webhook
              properties:
                webhook:
                  $ref: '#/components/schemas/WebhookInput'
      responses:
        '200':
          description: The updated webhook
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhook:
                    $ref: '#/components/schemas/Webhook'
    delete:
      operationId: deleteWebhook
      summary: Shopify Delete a webhook subscription
      description: Deletes a webhook subscription.
      tags:
      - Webhooks
      parameters:
      - name: webhook_id
        in: path
        required: true
        description: The ID of the webhook
        schema:
          type: integer
      responses:
        '200':
          description: Webhook deleted successfully
components:
  schemas:
    Webhook:
      type: object
      description: A webhook subscription
      properties:
        id:
          type: integer
        address:
          type: string
          format: uri
          description: The URL where the webhook delivers data
        topic:
          type: string
          description: The event that triggers the webhook
        format:
          type: string
          description: The data format
          enum:
          - json
          - xml
        fields:
          type: array
          description: Optional list of fields to include in the payload
          items:
            type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        api_version:
          type: string
          description: The API version for the webhook payload
        admin_graphql_api_id:
          type: string
    Error:
      type: object
      description: Error response
      properties:
        errors:
          description: Error details
          oneOf:
          - type: string
          - type: object
            additionalProperties:
              type: array
              items:
                type: string
    WebhookInput:
      type: object
      description: Input for creating or updating a webhook
      required:
      - topic
      - address
      properties:
        topic:
          type: string
          description: The event topic (e.g. orders/create)
        address:
          type: string
          format: uri
          description: The callback URL
        format:
          type: string
          enum:
          - json
          - xml
        fields:
          type: array
          items:
            type: string
  securitySchemes:
    AccessToken:
      type: apiKey
      name: X-Shopify-Access-Token
      in: header
      description: Access token obtained via OAuth