Adobe Commerce Webhooks

asyncapi: 2.6.0
info:
  title: Adobe Commerce Webhooks
  description: >-
    Adobe Commerce Webhooks enable developers to configure synchronous HTTP
    callbacks that fire when specific events occur within a Commerce instance,
    allowing external systems to react in real time to store activity. Webhooks
    can intercept and modify request data before Commerce processes it
    (synchronous before-hooks), or trigger outbound notifications after an
    event completes (synchronous after-hooks). Common use cases include
    integration with order management systems, fraud detection services, ERP
    platforms, and third-party fulfillment workflows. Webhook definitions are
    managed through the Commerce Admin UI, the REST API, or the webhooks.xml
    configuration file. Events are identified by the observer.* or plugin.*
    prefix naming convention. This specification documents the outbound webhook
    HTTP request payloads Commerce sends to configured receiver URLs.
  version: '1.0'
  contact:
    name: Adobe Commerce Developer Support
    url: https://developer.adobe.com/commerce/extensibility/webhooks/
externalDocs:
  description: Adobe Commerce Webhooks Documentation
  url: https://developer.adobe.com/commerce/extensibility/webhooks/
servers:
  commerceWebhookReceiver:
    url: '{receiverUrl}'
    protocol: https
    description: >-
      The external HTTPS URL configured by the merchant to receive webhook
      POST requests from Adobe Commerce. The receiver URL is specified in
      the webhook definition and must be publicly accessible from the
      Commerce instance.
    variables:
      receiverUrl:
        default: https://your-integration.example.com/webhook
        description: The merchant-configured HTTPS endpoint that receives webhook payloads.
    security:
      - hmacSignature: []
channels:
  /webhook/observer.sales_order_place_after:
    description: >-
      Fired after a customer places an order. Contains the full order object
      including line items, billing and shipping addresses, and payment method.
      Used to notify downstream order management systems or ERPs of new orders.
    publish:
      operationId: receiveSalesOrderPlaceAfter
      summary: Order placed event
      description: >-
        Triggered when a new sales order is successfully placed. The payload
        includes the complete order object with all items, totals, addresses,
        and payment information. This is the primary webhook for integrating
        Commerce order data with external fulfilment and ERP systems.
      message:
        $ref: '#/components/messages/SalesOrderPlaceAfter'

  /webhook/observer.sales_order_save_after:
    description: >-
      Fired after any order save operation, including status changes, comment
      additions, and shipment or invoice creation. Useful for monitoring order
      lifecycle changes and propagating status updates to external systems.
    publish:
      operationId: receiveSalesOrderSaveAfter
      summary: Order updated event
      description: >-
        Triggered after any modification to an existing order record, including
        status transitions, payment captures, shipment creation, and admin
        edits. The payload includes the updated order object with its current
        state and status.
      message:
        $ref: '#/components/messages/SalesOrderSaveAfter'

  /webhook/observer.sales_order_invoice_pay:
    description: >-
      Fired after an order invoice is marked as paid and payment has been
      captured. Used to trigger downstream accounting or revenue recognition
      workflows.
    publish:
      operationId: receiveSalesOrderInvoicePay
      summary: Invoice paid event
      description: >-
        Triggered when payment is captured for an order invoice. The payload
        includes the invoice object with its associated order reference and
        payment totals.
      message:
        $ref: '#/components/messages/SalesOrderInvoicePay'

  /webhook/observer.sales_order_shipment_save_after:
    description: >-
      Fired after a shipment record is created or updated for an order. Used
      to relay tracking information and shipment status to external logistics
      platforms or customer notification systems.
    publish:
      operationId: receiveSalesOrderShipmentSaveAfter
      summary: Order shipment saved event
      description: >-
        Triggered after a shipment is created or updated. The payload includes
        the shipment object with associated tracking numbers, carrier codes, and
        the items that were shipped.
      message:
        $ref: '#/components/messages/SalesOrderShipmentSaveAfter'

  /webhook/observer.customer_save_after_data_object:
    description: >-
      Fired after a customer account is created or updated. Used to synchronize
      customer profile data with external CRM, marketing automation, or loyalty
      systems.
    publish:
      operationId: receiveCustomerSaveAfterDataObject
      summary: Customer saved event
      description: >-
        Triggered after a customer account record is created or modified. The
        payload includes the customer data object with current and original
        field values, enabling detection of which fields changed.
      message:
        $ref: '#/components/messages/CustomerSaveAfterDataObject'

  /webhook/observer.customer_delete_after:
    description: >-
      Fired after a customer account is deleted. Used to propagate account
      deletion to external CRM or marketing systems and honor data removal
      requests.
    publish:
      operationId: receiveCustomerDeleteAfter
      summary: Customer deleted event
      description: >-
        Triggered after a customer account is permanently deleted from Commerce.
        The payload includes the customer entity that was deleted, providing
        the ID and email needed to remove the record from integrated systems.
      message:
        $ref: '#/components/messages/CustomerDeleteAfter'

  /webhook/observer.catalog_product_save_after:
    description: >-
      Fired after a product is created or updated in the catalog. Used to
      synchronize product data with external PIM systems, search indexes, or
      marketplace integrations.
    publish:
      operationId: receiveCatalogProductSaveAfter
      summary: Product saved event
      description: >-
        Triggered after a product record is saved. The payload includes the
        product object with its current attribute values. Both new product
        creation and updates to existing products fire this event.
      message:
        $ref: '#/components/messages/CatalogProductSaveAfter'

  /webhook/observer.checkout_cart_product_add_after:
    description: >-
      Fired after a product is added to a customer's shopping cart. Used for
      real-time cart analytics, personalization, or fraud detection integrations.
    publish:
      operationId: receiveCheckoutCartProductAddAfter
      summary: Product added to cart event
      description: >-
        Triggered when a product is successfully added to a shopping cart.
        The payload includes the cart item that was added along with the
        updated quote object.
      message:
        $ref: '#/components/messages/CheckoutCartProductAddAfter'

components:
  securitySchemes:
    hmacSignature:
      type: httpApiKey
      in: header
      name: X-Adobe-Signature
      description: >-
        HMAC-SHA256 signature of the request body using a shared secret configured
        in the webhook definition. Receivers should verify this signature to
        authenticate that the request originated from Adobe Commerce.

  messages:
    SalesOrderPlaceAfter:
      name: SalesOrderPlaceAfter
      title: Sales Order Placed
      summary: Payload sent when a new order is placed in Commerce.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/SalesOrderPayload'

    SalesOrderSaveAfter:
      name: SalesOrderSaveAfter
      title: Sales Order Saved
      summary: Payload sent when an order record is created or updated.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/SalesOrderPayload'

    SalesOrderInvoicePay:
      name: SalesOrderInvoicePay
      title: Sales Order Invoice Paid
      summary: Payload sent when payment is captured for an invoice.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/InvoicePayload'

    SalesOrderShipmentSaveAfter:
      name: SalesOrderShipmentSaveAfter
      title: Sales Order Shipment Saved
      summary: Payload sent when a shipment is created or updated.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ShipmentPayload'

    CustomerSaveAfterDataObject:
      name: CustomerSaveAfterDataObject
      title: Customer Account Saved
      summary: Payload sent when a customer account is created or updated.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CustomerPayload'

    CustomerDeleteAfter:
      name: CustomerDeleteAfter
      title: Customer Account Deleted
      summary: Payload sent when a customer account is deleted.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CustomerPayload'

    CatalogProductSaveAfter:
      name: CatalogProductSaveAfter
      title: Catalog Product Saved
      summary: Payload sent when a product is created or updated.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ProductPayload'

    CheckoutCartProductAddAfter:
      name: CheckoutCartProductAddAfter
      title: Product Added to Cart
      summary: Payload sent when a product is added to a shopping cart.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CartAddPayload'

  schemas:
    WebhookEnvelope:
      type: object
      description: >-
        The outer envelope wrapping all Commerce webhook payloads. Contains
        metadata about the event and the nested event data object.
      properties:
        merchant_id:
          type: string
          description: Identifier of the Commerce merchant instance that sent the event.
        environment_id:
          type: string
          description: Environment identifier (e.g. production, staging).
        event:
          type: string
          description: The full webhook event name (e.g. observer.sales_order_place_after).
        event_id:
          type: string
          format: uuid
          description: Unique identifier for this specific event invocation.
        data:
          type: object
          description: The event-specific payload data.

    SalesOrderPayload:
      type: object
      description: Webhook payload for sales order events.
      properties:
        order:
          $ref: '#/components/schemas/OrderData'

    OrderData:
      type: object
      description: Order data included in order-related webhook payloads.
      properties:
        entity_id:
          type: integer
          description: Numeric order entity ID.
        increment_id:
          type: string
          description: Human-readable order number (e.g. 000000001).
        status:
          type: string
          description: Current order status code (e.g. pending, processing, complete).
        state:
          type: string
          description: Internal order state machine state.
        customer_id:
          type: integer
          description: Numeric customer entity ID. Null for guest orders.
        customer_email:
          type: string
          format: email
          description: Email address of the customer or guest.
        customer_firstname:
          type: string
          description: Customer first name.
        customer_lastname:
          type: string
          description: Customer last name.
        customer_is_guest:
          type: integer
          description: Whether the order is a guest order. 1 = guest, 0 = registered customer.
          enum: [0, 1]
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the order was created.
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the order was last modified.
        grand_total:
          type: string
          description: Order grand total as a decimal string.
        subtotal:
          type: string
          description: Order subtotal before tax and shipping as a decimal string.
        tax_amount:
          type: string
          description: Total tax amount as a decimal string.
        shipping_amount:
          type: string
          description: Shipping amount as a decimal string.
        discount_amount:
          type: string
          description: Discount amount as a decimal string.
        base_currency_code:
          type: string
          description: ISO 4217 currency code for the base currency.
        order_currency_code:
          type: string
          description: ISO 4217 currency code for the order display currency.
        billing_address:
          $ref: '#/components/schemas/AddressData'
        shipping_address:
          $ref: '#/components/schemas/AddressData'
        items:
          type: array
          description: Line items in the order.
          items:
            $ref: '#/components/schemas/OrderItemData'
        payment:
          $ref: '#/components/schemas/PaymentData'

    OrderItemData:
      type: object
      description: A line item in an order webhook payload.
      properties:
        item_id:
          type: integer
          description: Numeric order item entity ID.
        sku:
          type: string
          description: Product SKU.
        name:
          type: string
          description: Product name at time of purchase.
        product_id:
          type: integer
          description: Numeric product entity ID.
        product_type:
          type: string
          description: Product type (simple, configurable, etc.).
        qty_ordered:
          type: string
          description: Quantity ordered as a decimal string.
        price:
          type: string
          description: Unit price as a decimal string.
        row_total:
          type: string
          description: Row total as a decimal string.
        tax_amount:
          type: string
          description: Tax amount for this line item.

    AddressData:
      type: object
      description: Address data included in order and customer webhook payloads.
      properties:
        firstname:
          type: string
          description: First name of the address recipient.
        lastname:
          type: string
          description: Last name of the address recipient.
        email:
          type: string
          format: email
          description: Email address.
        street:
          description: Street address lines as an array or newline-separated string.
        city:
          type: string
          description: City name.
        region:
          type: string
          description: State or region name.
        region_code:
          type: string
          description: State or region code.
        country_id:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          minLength: 2
          maxLength: 2
        postcode:
          type: string
          description: Postal code.
        telephone:
          type: string
          description: Phone number.

    PaymentData:
      type: object
      description: Payment method data included in order webhook payloads.
      properties:
        method:
          type: string
          description: Payment method code (e.g. checkmo, braintree, free).
        amount_paid:
          type: string
          description: Amount paid as a decimal string.
        base_amount_paid:
          type: string
          description: Base currency amount paid as a decimal string.

    InvoicePayload:
      type: object
      description: Webhook payload for invoice payment events.
      properties:
        invoice:
          type: object
          description: Invoice data object.
          properties:
            entity_id:
              type: integer
              description: Numeric invoice entity ID.
            order_id:
              type: integer
              description: Numeric entity ID of the parent order.
            increment_id:
              type: string
              description: Human-readable invoice number.
            grand_total:
              type: string
              description: Invoice grand total as a decimal string.
            state:
              type: integer
              description: Invoice state. 2 = paid.
            created_at:
              type: string
              format: date-time
              description: ISO 8601 timestamp when the invoice was created.

    ShipmentPayload:
      type: object
      description: Webhook payload for shipment events.
      properties:
        shipment:
          type: object
          description: Shipment data object.
          properties:
            entity_id:
              type: integer
              description: Numeric shipment entity ID.
            order_id:
              type: integer
              description: Numeric entity ID of the parent order.
            increment_id:
              type: string
              description: Human-readable shipment number.
            created_at:
              type: string
              format: date-time
              description: ISO 8601 timestamp when the shipment was created.
            tracks:
              type: array
              description: Tracking information records for this shipment.
              items:
                type: object
                properties:
                  carrier_code:
                    type: string
                    description: Carrier code (e.g. ups, fedex, usps).
                  title:
                    type: string
                    description: Human-readable carrier name.
                  track_number:
                    type: string
                    description: Carrier tracking number.
            items:
              type: array
              description: Products included in this shipment.
              items:
                type: object
                properties:
                  sku:
                    type: string
                    description: Product SKU.
                  name:
                    type: string
                    description: Product name.
                  qty:
                    type: number
                    description: Quantity shipped.

    CustomerPayload:
      type: object
      description: Webhook payload for customer account events.
      properties:
        customer:
          $ref: '#/components/schemas/CustomerData'

    CustomerData:
      type: object
      description: Customer data object included in customer event payloads.
      properties:
        entity_id:
          type: integer
          description: Numeric customer entity ID.
        email:
          type: string
          format: email
          description: Customer email address.
        firstname:
          type: string
          description: Customer first name.
        lastname:
          type: string
          description: Customer last name.
        group_id:
          type: integer
          description: Customer group ID.
        store_id:
          type: integer
          description: Store view ID where the customer account belongs.
        website_id:
          type: integer
          description: Website ID associated with the customer account.
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the account was created.
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the account was last modified.

    ProductPayload:
      type: object
      description: Webhook payload for catalog product events.
      properties:
        product:
          type: object
          description: Product data object.
          properties:
            entity_id:
              type: integer
              description: Numeric product entity ID.
            sku:
              type: string
              description: Product SKU.
            name:
              type: string
              description: Product display name.
            type_id:
              type: string
              description: Product type (simple, configurable, virtual, etc.).
            status:
              type: integer
              description: Product status. 1 = enabled, 2 = disabled.
              enum: [1, 2]
            price:
              type: number
              description: Product base price.
            created_at:
              type: string
              format: date-time
              description: ISO 8601 timestamp when the product was created.
            updated_at:
              type: string
              format: date-time
              description: ISO 8601 timestamp when the product was last updated.

    CartAddPayload:
      type: object
      description: Webhook payload for cart product add events.
      properties:
        quote_item:
          type: object
          description: The cart item that was added.
          properties:
            item_id:
              type: integer
              description: Numeric cart item entity ID.
            sku:
              type: string
              description: SKU of the added product.
            name:
              type: string
              description: Product display name.
            qty:
              type: number
              description: Quantity added to the cart.
            price:
              type: number
              description: Unit price of the product.
            product_id:
              type: integer
              description: Numeric product entity ID.
            product_type:
              type: string
              description: Product type.
            quote_id:
              type: string
              description: Cart (quote) ID this item was added to.