Webhooks

Autopilot provides the ability to receive notifications via http based on certain events (Webhook).

🔧 Technical Details

We’re using HTTPS to deliver a JSON payload to a provided URL using the POST method. The payload structure depends on the event type. We recommend choosing different URLs for different event types.

The supported event types are:

• Product listing patch published

• Product listing issue change (new / removed issues)

🔐 Authentication

For authentication we support adding a shared secret to the request header, for instance Authorization: Token <shared secret>. This allows you to easily validate any incoming request to the provided URL.

🛠️ Implementation Considerations

You can use your favorite tech stack to process the incoming notification and trigger the necessary actions to your internal systems.

We recommend that you process any complex operations in the background, i.e. after confirming that the webhook was correctly received by returning a 2xx HTTP result code (usually 200 or 201).

In case we receive a 4xx/5xx HTTP result code, the webhook will be retried up to 20 times with a progressive backoff.

We include a X-Request-Id header in every request which we recommend logging in case of issues with the received payload.

We’re using an at-least-once delivery paradigm so any actions on your side should be idempotent. Further, the ordering of delivery isn’t guaranteed. For instance in case of error responses from your endpoint the delivery will be retried at a later time. All our payloads include timestamps which will help you resolve those cases.

📝 Payload Schemas

In this section you can find the JSON schemas for the different event types.

Product listing patch published

//
id: https://product_historian.apps.autopilotbrand.com/models/notifications/patch_notification
title: Autopilot Patch Notification
description: Contents of notifications we're sending after a patch was sent to Amazon

"$ref": "#/components/schemas/ListingChangeNotification"

components:
  schemas:
    ListingChangeNotification:
      type: object
      properties:
        seller_id:
          type: string
          description: Selling partner identifier, such as a merchant account or vendor code
        sku:
          type: string
          description: Selling partner provided identifier
        marketplace_id:
          type: string
          description: Amazon marketplace identifier
        created_at:
          type: string
          format: date-time
          description: Timestamp when change was created
        confirmed_at:
          type: string
          format: date-time
          description: Timestamp when change was confirmed submitted
        patch:
          "$ref": "#/components/schemas/ListingPatch"
      required:
      - seller_id
      - sku
      - marketplace_id
      - created_at
      - confirmed_at
      - patch

    ListingPatch:
      type: object
      properties:
        patches:
          description: "One or more JSON Patch operations to perform on the listings item."
          type: array
          items:
            "$ref": "#/components/schemas/PatchOperation"
          minItems: 1
      required:
      - patches

    PatchOperation:
      description: "Individual JSON Patch operation for an HTTP PATCH request."
      type: object
      properties:
        op:
          description: "Type of JSON Patch operation. Supported JSON Patch operations include add, replace, and delete. Refer to [JavaScript Object Notation (JSON) Patch](https://tools.ietf.org/html/rfc6902) for more information."
          enum:
          - add
          - replace
          - delete
          type: string
        path:
          description: JSON Pointer path of the element to patch. Note that for Amazon listings, JSON Patch documents can only add, replace, or delete entire attributes. Patching content within attributes is not supported.
          type: string
        value:
          description: JSON value to add, replace, or delete.
          type: array
          items:
            type: object
            additionalProperties: true
      required:
      - op
      - path

Product listing issue change

// 
id: https://product_historian.apps.autopilotbrand.com/models/notifications/issues
title: Autopilot Issues Notification
description: Contents of notifications we're sending when change to issues is detected

components:
  schemas:
    issue:
      type: object
      properties:
        code:
          type: string
          description: An issue code that identifies the type of issue.
        message:
          type: string
          description: A message that describes the issue.
        severity:
          description: The severity of the issue.
          type: string
          enum:
          - "ERROR"
          - "WARNING"
          - "INFO"
        attribute_name:
          type: string
          description: The names of the attribute associated with the issue, if applicable.
        enforcement:
          type: object
          description: Enforcement actions taken by Amazon that affect the publishing or status of a listing. It also includes details about any associated exemptions.
          properties:
            action:
              description: |
                The enforcement action name.
                Possible values:
                - `LISTING_SUPPRESSED` - This enforcement takes down the current listing item's buyability.
                - `ATTRIBUTE_SUPPRESSED` - An attribute's value on the listing item is invalid, which causes it to be rejected by Amazon.
                - `CATALOG_ITEM_REMOVED` - This catalog item is inactive on Amazon, and all offers against it in the applicable marketplace are non-buyable.
                - `SEARCH_SUPPRESSED` - This value indicates that the catalog item is hidden from search results.
              type: string
              enum:
              - LISTING_SUPPRESSED
              - ATTRIBUTE_SUPPRESSED
              - CATALOG_ITEM_REMOVED
              - SEARCH_SUPPRESSED
            exemption:
              description: The status of the listed enforcement actions and, if applicable, provides information about the exemption's expiry date.
              type: object
              properties:
                status:
                  description: Current exemption status. It can take values such as `EXEMPT`, signifying permanent exemption, `EXEMPT_UNTIL_EXPIRY_DATE` indicating temporary exemption until a specified date, or `NOT_EXEMPT` signifying no exemptions, and enforcement actions were already applied."
                  type: string
                  enum:
                  - EXEMPT
                  - EXEMPT_UNTIL_EXPIRY_DATE
                  - NOT_EXEMPT
                expiry_date:
                  description: Specifies the time when temporary exemptions will expire, and Amazon will begin enforcing the action.
                  type: string
                  format: date-time
              required:
              - status
          required:
          - action
          - exemption
      required:
      - code
      - message
      - severity
    issue_list:
      type: array
      items:
        "$ref": "#/components/schemas/issue"

type: object
properties:
  seller_id:
    type: string
  sku:
    type: string
  asin:
    type: string
  marketplace_id:
    type: string
  detected_at:
    type: string
    format: date-time
  new_issues:
    "$ref": "#/components/schemas/issue_list"
  resolved_issues:
    "$ref": "#/components/schemas/issue_list"
required:
- seller_id
- sku
- asin
- marketplace_id
- detected_at
- new_issues
- resolved_issues