Creating a Simple Webhook

Configure a Webhook

    • Login to and navigate to Home  →  Configuration  →  Development  →  Webhooks.
    • Click the New Webhook button.
    • Enter the Target URL.  This is the full, absolute URL of your server.   For this example, we entered
    • API Version: Leave this at Latest Version if possible.  If your webhook is mission critical, then specify a version to avoid changes.
    • Authentication Type:  For this example, we used no Authentication.  You may configure Basic authentication if desired.
    • Event Subscription: Select which events to receive for this webhook.  

  • Add the expansion you need.  The expansion is a csv list of which order parts you desire.  For event_ship, you may only need the shipping part of an order.  This reduces payload size considerably.  The list of expansions are here:  (you'll need to click on the Expansion link under the Order section in the left hand navigation).
    • For this example, we added the kitchen sink.  affiliate,affiliate.ledger,auto_order,billing,buysafe,channel_partner,checkout,coupon,customer_profile,digital_order,edi,fraud_score,gift,gift_certificate,internal,item,linked_shipment,marketing,payment,payment.transaction,quote,salesforce,shipping,summary,taxes
  • Message Payload: Configure Max Size and Max Events / Payload
  • Click the Save button
  • After saving, edit the webhook and add any expansions needed.  See for expansion lists.

Additional Step for Fulfillment Webhooks

Fulfillment webhooks are designed to fire for a specific distribution center.   The webhook must be connected to the distribution center.  Here are the steps:

  • After fully creating your webhook using the steps above, navigate to the Distribution Centers.

Home → Configuration → Checkout → Shipping → Distribution Centers (4th tab on Shipping screen)

Shortcut link:

  • Find the target distribution center and click the edit button.
  • Click on the Transmission Mechanism tab when the distribution center loads.
  • Scroll down until you find the mechanism named REST.  Select that mechanism.
  • Select the API User and then the webhook.
  • Save your changes.

Webhook Script Examples

The webhook will receive a JSON payload as a POST body.   The structure of the payload is an array of simple objects with key = event_name and value = object.

Test your Webhook

Once your webhook script is deployed, test out your webhook by clicking the test button on the configuration screen.  All webhooks have detailed logging accessible via the log button.

Sample JSON Payload

This webhook contains an order_create event.  Note that all payloads are arrays of events, even those containing a single event.

Alternatives to JSON format

If you're interested in extracting a sub-set of the JSON data into a flatter format, I would really encourage you to have a look at our Data Warehouse for BigQuery.  You can have all that order information flow into your BigQuery account for next to nothing cost wise.  It's incredibly economical.  You can then write queries to extract a sub-set of the data into a flat result and save that as a "view".  From there you can do:

  • easy reporting in Google Data Studio / Microsoft Power BI

  • connect data to Microsoft Excel or Google Sheets

  • extract querying using the BigQuery CLI or SDK to extract the data set