openapi: 3.0.0
info:
  title: Gearment Webhook API
  description: >
    The Gearment Webhook API provides real-time notifications for critical order
    and product events—such as order completion, cancellation, shipping updates,
    stock changes, and variant modifications—across multiple payload versions to
    ensure seamless integration with your existing systems.
  version: 1.0.0
  contact:
    email: integration@gearment.com
    name: Support Integration
servers:
  - url: https://your-webhook-url
    description: Your Webhook URL
paths: {}
components:
  schemas:
    WebhookPayloadV1:
      type: object
      description: Version 1 webhook payload format
      required:
        - api_key
        - type
        - data
      properties:
        api_key:
          type: string
          description: API key for webhook validation
          example: xxxxxxxxxxxx
        type:
          type: string
          description: The event type that triggered the webhook
          enum:
            - order_completed
            - order_canceled
            - tracking_updated
            - order_on_hold
            - shipping_address_verified
            - shipping_address_unverified
            - product_out_of_stock
            - variant_created
            - variant_updated
        data:
          oneOf:
            - $ref: '#/components/schemas/OrderCompletedPayloadV1'
            - $ref: '#/components/schemas/OrderCancelledPayloadV1'
            - $ref: '#/components/schemas/TrackingUpdatedPayloadV1'
            - $ref: '#/components/schemas/OrderOnHoldPayloadV1'
            - $ref: '#/components/schemas/ShippingAddressVerifiedPayloadV1'
            - $ref: '#/components/schemas/ShippingAddressUnverifiedPayloadV1'
            - $ref: '#/components/schemas/ProductVariantOutStockPayloadV1'
            - $ref: '#/components/schemas/VariantCreatedPayloadV1'
            - $ref: '#/components/schemas/VariantUpdatedPayloadV1'
    WebhookPayloadV3:
      type: object
      description: Version 3 webhook payload format
      required:
        - type
      properties:
        type:
          type: string
          description: The event type that triggered the webhook
          enum:
            - order_completed
            - order_cancelled
            - tracking_order_updated
            - order_on_hold
            - shipping_address_verified
            - shipping_address_unverified
            - product_out_of_stock
            - variant_created
            - variant_updated
        order:
          type: object
          description: Order information (present in order-related events)
        tracking:
          type: object
          description: Tracking information (present in tracking-related events)
        variant:
          type: object
          description: Variant information (present in variant-related events)
        data:
          type: array
          description: Product data (present in product-related events)
    OrderCompletedPayloadV1:
      type: object
      description: Version 1 webhook payload for completed orders
      required:
        - api_key
        - type
        - data
      properties:
        api_key:
          type: string
          description: API key for webhook validation
          example: xxxxxxxxxxxx
        type:
          type: string
          description: Event type
          enum:
            - order_completed
          example: order_completed
        data:
          type: object
          description: Order data payload
          required:
            - gearment_ord_id
            - gearment_ord_name
            - ord_status
            - order_id
            - tracking_number
            - tracking_company
            - tracking_url
          properties:
            gearment_ord_id:
              type: string
              description: Gearment order ID
              example: ORD123456789
            gearment_ord_name:
              type: string
              description: Gearment order name
              example: '#10001'
            ord_status:
              type: string
              description: Order status
              example: completed
            order_id:
              type: string
              description: External order ID
              example: EXT-1234567
            tracking_number:
              type: string
              description: Shipment tracking number
              example: 1ZW470V80341905646
            tracking_company:
              type: string
              description: Shipping carrier
              example: UPS
            tracking_url:
              type: string
              description: Tracking URL
              example: https://www.ups.com/track?tracknum=1ZW470V80341905646
    OrderCancelledPayloadV1:
      type: object
      description: Version 1 webhook payload for order cancellation
      required:
        - api_key
        - type
        - data
      properties:
        api_key:
          type: string
          description: API key for webhook validation
          example: xxxxxxxxxxxx
        type:
          type: string
          description: Event type
          enum:
            - order_cancelled
          example: order_cancelled
        data:
          type: object
          required:
            - api_key
            - gearment_ord_id
            - gearment_ord_name
            - ord_status
            - order_id
          properties:
            api_key:
              type: string
              description: API key inside the data section (duplicated)
              example: xxxxxxxxxxxx
            gearment_ord_id:
              type: string
              description: Gearment order ID
              example: ORD123456789
            gearment_ord_name:
              type: string
              description: Gearment order name
              example: '#10001'
            ord_status:
              type: string
              description: Order status - will be "canceled"
              example: canceled
            order_id:
              type: string
              description: External order ID
              example: EXT-1234567
    TrackingUpdatedPayloadV1:
      type: object
      description: Version 1 webhook payload for tracking updates
      required:
        - api_key
        - type
        - data
      properties:
        api_key:
          type: string
          description: API key for webhook validation
          example: xxxxxxxxxxxx
        type:
          type: string
          description: Event type
          enum:
            - tracking_updated
          example: tracking_updated
        data:
          type: object
          required:
            - gearment_ord_id
            - gearment_ord_name
            - ord_status
            - order_id
            - tracking_number
            - tracking_company
            - tracking_url
          properties:
            gearment_ord_id:
              type: string
              description: Gearment order ID
              example: ORD123456789
            gearment_ord_name:
              type: string
              description: Gearment order name
              example: '#10001'
            ord_status:
              type: string
              description: Order status (fixed as "processing")
              example: processing
            order_id:
              type: string
              description: External order ID
              example: EXT-1234567
            tracking_number:
              type: string
              description: Shipment tracking number
              example: 1ZW470V80341905646
            tracking_company:
              type: string
              description: Shipping carrier
              example: UPS
            tracking_url:
              type: string
              description: Tracking URL
              example: https://www.ups.com/track?tracknum=1ZW470V80341905646
    OrderOnHoldPayloadV1:
      type: object
      description: Version 1 webhook payload for order on hold
      required:
        - type
        - data
      properties:
        type:
          type: string
          description: Event type
          enum:
            - order_on_hold
          example: order_on_hold
        data:
          type: object
          required:
            - gearment_ord_id
            - gearment_ord_name
            - reason
            - order_id
          properties:
            gearment_ord_id:
              type: string
              description: Gearment order ID
              example: ORD123456789
            gearment_ord_name:
              type: string
              description: Gearment order name
              example: '#10001'
            reason:
              type: string
              description: Reason for placing order on hold
              example: Address validation required
            order_id:
              type: string
              description: External order ID
              example: EXT-1234567
    ShippingAddressVerifiedPayloadV1:
      type: object
      description: Version 1 webhook payload for verified shipping address
      required:
        - type
        - data
      properties:
        type:
          type: string
          description: Event type
          enum:
            - shipping_address_verified
          example: shipping_address_verified
        data:
          type: object
          required:
            - gearment_ord_id
            - gearment_ord_name
            - ord_status
            - verify_address
            - order_id
          properties:
            gearment_ord_id:
              type: string
              description: Gearment order ID
              example: ORD123456789
            gearment_ord_name:
              type: string
              description: Gearment order name
              example: '#10001'
            ord_status:
              type: string
              description: Order status
              example: pending
            verify_address:
              type: string
              description: Address verification status
              example: verified
            order_id:
              type: string
              description: External order ID
              example: EXT-1234567
    ShippingAddressUnverifiedPayloadV1:
      type: object
      description: Version 1 webhook payload for unverified shipping address
      required:
        - type
        - data
      properties:
        type:
          type: string
          description: Event type
          enum:
            - shipping_address_unverified
          example: shipping_address_unverified
        data:
          type: object
          required:
            - gearment_ord_id
            - gearment_ord_name
            - ord_status
            - verified_address
            - order_id
          properties:
            gearment_ord_id:
              type: string
              description: Gearment order ID
              example: ORD123456789
            gearment_ord_name:
              type: string
              description: Gearment order name
              example: '#10001'
            ord_status:
              type: string
              description: Order status
              example: pending
            verified_address:
              type: string
              description: Address verification
              example: unverified
            order_id:
              type: string
              description: External order ID
              example: EXT-1234567
    ProductVariantOutStockPayloadV1:
      type: object
      description: Version 1 webhook payload for out-of-stock product variants
      required:
        - api_key
        - type
        - data
      properties:
        api_key:
          type: string
          description: API key for webhook validation
          example: xxxxxxxxxxxx
        type:
          type: string
          description: Event type
          enum:
            - product_out_of_stock
          example: product_out_of_stock
        data:
          type: array
          description: List of out-of-stock product variants
          items:
            type: object
            required:
              - product_name
              - product_id
              - product_img
              - print_areas
              - variants
            properties:
              product_name:
                type: string
                description: Product name
                example: Premium T-Shirt
              product_id:
                type: string
                description: Product ID
                example: PROD-12345
              product_img:
                type: string
                description: URL to product image
                example: https://cdn.gearment.com/images/products/12345.jpg
              print_areas:
                type: array
                description: Available print locations
                items:
                  type: string
                example:
                  - front
                  - back
              variants:
                type: object
                required:
                  - variant_id
                  - name
                  - size
                  - color
                  - hex_color_code
                  - price
                  - extra_price
                  - availability_status
                properties:
                  variant_id:
                    type: string
                    description: Variant ID
                    example: VAR-12345
                  name:
                    type: string
                    description: Variant name
                    example: Black / XL
                  size:
                    type: string
                    description: Size
                    example: XL
                  color:
                    type: string
                    description: Color name
                    example: Black
                  hex_color_code:
                    type: string
                    description: Color hex code
                    example: '#000000'
                  price:
                    type: string
                    description: Base price
                    example: '19.99'
                  extra_price:
                    type: string
                    description: Extra price for this variant
                    example: '2.00'
                  availability_status:
                    type: string
                    description: Stock status
                    example: out_of_stock
    VariantCreatedPayloadV1:
      type: object
      properties:
        variant_created:
          type: boolean
          description: Indicates a variant has been created
          example: true
    VariantUpdatedPayloadV1:
      type: object
      properties:
        variant_updated:
          type: boolean
          description: Indicates a variant has been updated
          example: true
    OrderCompletedPayloadV3:
      type: object
      required:
        - type
        - order
        - tracking
      properties:
        type:
          type: string
          enum:
            - order_completed
        order:
          type: object
          properties:
            gearment_id:
              type: string
              description: Gearment order ID
              example: ORD123456789
            gearment_name:
              type: string
              description: Gearment order name
              example: '#10001'
            vendor_id:
              type: string
              description: External vendor ID
              example: EXT-1234567
            reference:
              type: string
              description: Reference ID
              example: REF-1234567
            status:
              type: string
              description: Order status
              example: shipped
        tracking:
          type: object
          properties:
            number:
              type: string
              description: Tracking number
              example: 1ZW470V80341905646
            company:
              type: string
              description: Shipping carrier name
              example: UPS
            url:
              type: string
              description: Tracking URL
              example: https://www.ups.com/track?tracknum=1ZW470V80341905646
    OrderCancelledPayloadV3:
      type: object
      required:
        - type
        - order
      properties:
        type:
          type: string
          enum:
            - order_cancelled
        order:
          type: object
          properties:
            gearment_id:
              type: string
              description: Gearment order ID
              example: ORD123456789
            gearment_name:
              type: string
              description: Gearment order name
              example: '#10001'
            vendor_id:
              type: string
              description: External vendor ID
              example: EXT-1234567
            status:
              type: string
              description: Order status
              example: cancelled
    TrackingUpdatedPayloadV3:
      type: object
      required:
        - type
        - order
        - tracking
      properties:
        type:
          type: string
          enum:
            - tracking_order_updated
        order:
          type: object
          properties:
            gearment_id:
              type: string
              description: Gearment order ID
              example: ORD123456789
            gearment_name:
              type: string
              description: Gearment order name
              example: '#10001'
            vendor_id:
              type: string
              description: External vendor ID
              example: EXT-1234567
            status:
              type: string
              description: Order status
              example: in-production
        tracking:
          type: object
          properties:
            number:
              type: string
              description: Tracking number
              example: 1ZW470V80341905646
            company:
              type: string
              description: Shipping carrier name
              example: UPS
            url:
              type: string
              description: Tracking URL
              example: https://www.ups.com/track?tracknum=1ZW470V80341905646
    OrderOnHoldPayloadV3:
      type: object
      required:
        - type
        - order
      properties:
        type:
          type: string
          enum:
            - order_on_hold
        order:
          type: object
          properties:
            gearment_id:
              type: string
              description: Gearment order ID
              example: ORD123456789
            gearment_name:
              type: string
              description: Gearment order name
              example: '#10001'
            vendor_id:
              type: string
              description: External vendor ID
              example: EXT-1234567
            reason:
              type: string
              description: Reason for hold
              example: Address validation required
    ShippingAddressVerifiedPayloadV3:
      type: object
      required:
        - type
        - order
      properties:
        type:
          type: string
          enum:
            - shipping_address_verified
        order:
          type: object
          properties:
            gearment_id:
              type: string
              description: Gearment order ID
              example: ORD123456789
            gearment_name:
              type: string
              description: Gearment order name
              example: '#10001'
            vendor_id:
              type: string
              description: External vendor ID
              example: EXT-1234567
            verify_address:
              type: string
              description: Address verification status
              example: verified
            ord_status:
              type: string
              description: Order status
              example: pending
    ShippingAddressUnverifiedPayloadV3:
      type: object
      required:
        - type
        - order
      properties:
        type:
          type: string
          enum:
            - shipping_address_unverified
        order:
          type: object
          properties:
            gearment_id:
              type: string
              description: Gearment order ID
              example: ORD123456789
            gearment_name:
              type: string
              description: Gearment order name
              example: '#10001'
            vendor_id:
              type: string
              description: External vendor ID
              example: EXT-1234567
            verified_address:
              type: string
              description: Address verification status
              example: unverified
            ord_status:
              type: string
              description: Order status
              example: pending
    ProductVariantOutStockPayloadV3:
      type: object
      required:
        - type
        - data
      properties:
        type:
          type: string
          enum:
            - product_out_of_stock
        data:
          type: array
          items:
            type: object
            properties:
              product_name:
                type: string
                description: Product name
                example: Premium T-Shirt
              product_id:
                type: string
                description: Product ID
                example: PROD-12345
              product_img:
                type: string
                description: URL to product image
                example: https://cdn.gearment.com/images/products/12345.jpg
              print_areas:
                type: array
                description: Available print locations
                items:
                  type: string
                example:
                  - front
                  - back
              variants:
                type: object
                properties:
                  variant_id:
                    type: string
                    description: Variant ID
                    example: VAR-12345
                  name:
                    type: string
                    description: Variant name
                    example: Black / XL
                  size:
                    type: string
                    description: Size
                    example: XL
                  color:
                    type: string
                    description: Color name
                    example: Black
                  hex_color_code:
                    type: string
                    description: Color hex code
                    example: '#000000'
                  price:
                    type: string
                    description: Base price
                    example: '19.99'
                  extra_price:
                    type: string
                    description: Extra price for this variant
                    example: '2.00'
                  stock_label:
                    type: string
                    description: Stock status label
                    example: Out of stock
    VariantCreatedPayloadV3:
      type: object
      description: Webhook payload when a product variant is created (V3)
      required:
        - variant
      properties:
        variant:
          type: object
          required:
            - id
          properties:
            id:
              type: string
              description: Variant ID
              example: variant-id
    VariantUpdatedPayloadV3:
      type: object
      description: Webhook payload when a product variant is updated (V3)
      required:
        - variant
      properties:
        variant:
          type: object
          required:
            - id
          properties:
            id:
              type: string
              description: Variant ID
              example: '1234567890'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authenticating webhook registrations
tags:
  - name: Overview
    description: >-
      Webhook events are one-way events sent to your app over HTTP to notify you
      when an event occured. Unlike events that are sent over Gateway
      connections, events sent over webhooks are not realtime or guaranteed to
      be in order.


      While incoming webhooks are triggered by an external service, webhook
      events (i.e. outgoing webhooks) are triggered by events happening in
      Gearment. This means your app will need to set up a public URL where you
      can receive HTTP events, which is detailed in the preparing for events
      section.


      > You can configure only one webhook URL per webhook event and version.
       
      ### Setting Up Webhooks

      To configure webhook events, you'll need to configure your URL and select
      the events you want your app to receive.


      In your team's settings, navigate to the **Webhooks** page from the
      left-hand sidebar.

      1. Under **Developer Settings**, click **Webhooks**, add a **Add Webhook**
      that is set up to receive and acknowledge webhook events.
          - Details about payload found in the *Preparing for Events* section.
      2. Setup **Webhook name** and **Delivery URL** 

      3. Select the **webhook events** and **version** you want your app to
      receive. 

      4. Click **Save**.


      > If your URL is successfully verified, your app should begin receiving
      the events you selected.



      #### Simulate webhook


      To test your webhook URL, you can use the **Simulate Webhook** feature.
      This allows you to send a test payload to your webhook URL to ensure that
      it is set up correctly and can handle incoming requests.

      1. In the **Webhooks** page, click on the **Webhook simulator** button.

      2. Setup **Delivery URL**

      3. Select the event type you want to simulate.

      4. Click **Send**.
    x-displayName: Overview
  - name: Signature
    description: "When Gearment sends an alert payload to your webhook URL, we include a variety of headers that you can use to verify that the payload came from QuickAlerts. For additional security, you can implement **signature validation**, which is an optional way to verify the authenticity of payloads received by your webhook URL.\n\n---\n\n### Headers We Send\n\n| Header                  | Description                                                   |\n|-------------------------|---------------------------------------------------------------|\n| `X-Connect-Timestamp`   | The timestamp when this payload was sent.                     |\n| `X-Connect-Nonce`       | The nonce we used in the generation of the payload signature. |\n| `X-Connect-Signature`   | The signature we generated for this payload.                  |\n| `X-Connect-Client-Key`  | The key we use in the generation to sign                      |  \n\n---\n\n### Locating the Webhook Security Token\n\n1. Sign in to the [Gearment Developer Setting](https://dash.gearment.com/).\n2. Click to **Setting Teams**.\n3. Navigate on the **Developer settings** tab.\n4. Click to **API credentials**.\n5. Click to **Request API key**.\n6. In the details, find the **API key** and **API signature** field.\n\nThe **API key and signature** is a value known only to you and Gearment. It is used to generate a signature that can be validated on your end to ensure the authenticity of the received payloads.\n\n---\n\n\n### Signature Construction Logic\n\nThe HMAC-SHA256 signature is computed as follows:\n\n1. Read the **HTTP body** of the request.\n2. Base64-URL encode the body content.\n3. Construct a **signing string** using:\n   ```\n   <URL path> + <nonce> + <timestamp> + <base64-url-encoded body>\n   ```\n4. Compute the HMAC-SHA256 digest using your **client secret** as the key.\n5. Base64-URL encode the result.\n6. Compare the computed signature to the one provided in the `X-Connect-Signature` header.\n\n---\n\n####  Verifying a Payload\n\nBelow are code snippets demonstrating how to verify the signature for different programming languages. These examples assume that the webhook headers (`timestamp`, `nonce`, `signature`, etc.) are already available as variables. Replace the `clientSecret` constant with your Webhook Security Token.\n\n---\n\n**Go**\n\n```go\npackage main\n\nimport (\n\t\"crypto/hmac\"\n\t\"crypto/sha256\"\n\t\"encoding/base64\"\n\t\"io\"\n\t\"net/http\"\n\t\"strings\"\n)\n\nfunc verifySignature(r *http.Request) bool {\n\ttimestamp := r.Header.Get(\"X-Connect-Timestamp\")\n\tnonce := r.Header.Get(\"X-Connect-Nonce\")\n\tsignature := r.Header.Get(\"X-Connect-Signature\")\n\tclientKey := r.Header.Get(\"X-Connect-Client-Key\")\n\n\tclientSecret := \"client_secret\" // Replace with your actual secret\n\n\t// Read and preserve the body\n\tbodyBytes, err := io.ReadAll(r.Body)\n\tif err != nil {\n\t\treturn false\n\t}\n\t// Reset r.Body so it can be read again later if needed\n\tr.Body = io.NopCloser(strings.NewReader(string(bodyBytes)))\n\n\t// Base64 URL encode the body\n\tbodyEncoded := base64.URLEncoding.EncodeToString(bodyBytes)\n\n\t// Build the signing string\n\tsigningString := r.URL.Path + nonce + timestamp + bodyEncoded\n\n\t// Compute HMAC-SHA256\n\th := hmac.New(sha256.New, []byte(clientSecret))\n\th.Write([]byte(signingString))\n\texpectedSignature := base64.URLEncoding.EncodeToString(h.Sum(nil))\n\n\t// Constant-time comparison\n\treturn hmac.Equal([]byte(signature), []byte(expectedSignature))\n}\n```\n\n**NodeJS**\n```javascript\n// Replace with your actual secret\nconst clientSecret = '0TxSN1NN7A8_v3_AsbbCffjEPEchBewtuRHCUMvVHy0DOh422PaHrbAk5WccWW0F';\n\nfunction verifySignature(req: Request): boolean {\n    const timestamp = req.header('X-Connect-Timestamp');\n    const nonce = req.header('X-Connect-Nonce');\n    const signature = req.header('X-Connect-Signature');\n    const clientKey = req.header('X-Connect-Client-Key');\n\n    const rawBody = req.body;\n    if (!timestamp || !nonce || !signature || !clientKey) {\n        return false;\n    }\n    if (!rawBody) {\n        return false;\n    }\n    const bodyEncoded = base64UrlEncode(rawBody.toString());\n    const signingString = req.path + nonce + timestamp + bodyEncoded;\n\n    const expectedSignature = generateSignature(signingString, clientSecret);\n\n    // Secure compare\n    const result = crypto.timingSafeEqual(\n        Buffer.from(signature),\n        Buffer.from(expectedSignature)\n    );\n    return result;\n\n}\n\nexport function base64UrlEncode(input: string): string {\n    const encoded = typeof window === 'undefined'\n        ? Buffer.from(input).toString('base64')\n        : btoa(unescape(encodeURIComponent(input)));\n\n    return encoded.replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '');\n}\n\nfunction generateSignature(signingString: string, clientSecret: string): string {\n    const hmac = crypto.createHmac('sha256', clientSecret);\n\n    hmac.update(signingString);\n\n    const digest = hmac.digest();\n    // Base64 URL encode: replace '+' with '-', '/' with '_', and remove '=' padding\n    return digest.toString('base64').replace(/\\+/g, '-').replace(/\\//g, '_');\n}\n```\n\n**Java**\n```java\nprivate boolean verifySignature(HttpServletRequest request) throws IOException {\n        String timestamp = request.getHeader(\"X-Connect-Timestamp\");\n        String nonce = request.getHeader(\"X-Connect-Nonce\");\n        String signature = request.getHeader(\"X-Connect-Signature\");\n\n        // Read raw body\n        String body = new Scanner(request.getInputStream(), \"UTF-8\").useDelimiter(\"\\\\A\").next();\n        byte[] bodyBytes = body.getBytes(StandardCharsets.UTF_8);\n\n        // Base64 URL encode the body\n        String bodyEncoded = Base64.getUrlEncoder().withoutPadding().encodeToString(bodyBytes);\n\n        // Build signing string\n        String signingString = request.getRequestURI() + nonce + timestamp + bodyEncoded;\n\n        try {\n            Mac hmacSha256 = Mac.getInstance(\"HmacSHA256\");\n            SecretKeySpec secretKey = new SecretKeySpec(CLIENT_SECRET.getBytes(StandardCharsets.UTF_8), \"HmacSHA256\");\n            hmacSha256.init(secretKey);\n\n            byte[] hashBytes = hmacSha256.doFinal(signingString.getBytes(StandardCharsets.UTF_8));\n            String expectedSignature = Base64.getEncoder().encodeToString(hashBytes);\n\n            if (expectedSignature.equals(signature)) {\n                return true;\n            }\n        } catch (Exception e) {\n            e.printStackTrace();\n            return false;\n        }\n        return false;\n    }\n```"
    x-displayName: Signature
  - name: Payload
    description: Webhook events that can be received from Gearment
    x-displayName: Payload
x-webhooks:
  order_completed:
    post:
      summary: Order Completed
      description: Triggered when an order is completed and shipped to the customer
      tags:
        - Payload
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/OrderCompletedPayloadV1'
                - $ref: '#/components/schemas/OrderCompletedPayloadV3'
      responses:
        '200':
          description: Webhook processed successfully
  order_cancelled:
    post:
      summary: Order Cancelled
      description: Triggered when an order is cancelled
      tags:
        - Payload
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/OrderCancelledPayloadV1'
                - $ref: '#/components/schemas/OrderCancelledPayloadV3'
      responses:
        '200':
          description: Webhook processed successfully
  tracking_updated:
    post:
      summary: Order Tracking Updated
      description: Triggered when tracking information for an order is added or updated
      tags:
        - Payload
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/TrackingUpdatedPayloadV1'
                - $ref: '#/components/schemas/TrackingUpdatedPayloadV3'
      responses:
        '200':
          description: Webhook processed successfully
  order_on_hold:
    post:
      summary: Order On Hold
      description: Triggered when an order is placed on hold
      tags:
        - Payload
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/OrderOnHoldPayloadV1'
                - $ref: '#/components/schemas/OrderOnHoldPayloadV3'
      responses:
        '200':
          description: Webhook processed successfully
  shipping_address_verified:
    post:
      summary: Shipping Address Verified
      description: Triggered when a shipping address is verified
      tags:
        - Payload
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/ShippingAddressVerifiedPayloadV1'
                - $ref: '#/components/schemas/ShippingAddressVerifiedPayloadV3'
      responses:
        '200':
          description: Webhook processed successfully
  shipping_address_unverified:
    post:
      summary: Shipping Address Unverified
      description: Triggered when a shipping address cannot be verified
      tags:
        - Payload
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/ShippingAddressUnverifiedPayloadV1'
                - $ref: '#/components/schemas/ShippingAddressUnverifiedPayloadV3'
      responses:
        '200':
          description: Webhook processed successfully
  product_out_of_stock:
    post:
      summary: Product Variant Out of Stock
      description: Triggered when a product variant goes out of stock
      tags:
        - Payload
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/ProductVariantOutStockPayloadV1'
                - $ref: '#/components/schemas/ProductVariantOutStockPayloadV3'
      responses:
        '200':
          description: Webhook processed successfully
  variant_created:
    post:
      summary: Variant Created
      description: Triggered when a new product variant is created
      tags:
        - Payload
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/VariantCreatedPayloadV1'
                - $ref: '#/components/schemas/VariantCreatedPayloadV3'
      responses:
        '200':
          description: Webhook processed successfully
  variant_updated:
    post:
      summary: Variant Updated
      description: Triggered when a product variant is updated
      tags:
        - Payload
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/VariantUpdatedPayloadV1'
                - $ref: '#/components/schemas/VariantUpdatedPayloadV3'
      responses:
        '200':
          description: Webhook processed successfully
