Webhooks Overview

Webhooks are user-defined HTTP callbacks that are triggered when an order or shipment create/update event occurs. Whenever an event occurs, the webhook sees the event, collects the event data, and sends it to the Call Back URL specified by you in the form of an HTTP request. 

This is important as it allows you to get the latest information about your order or shipment when an event in our system occurs so that you can pass it back into your system.

Getting Started with Webhooks 

To get started with Webhooks, you’ll need to have (or build) a webhook handler to receive the webhook requests from our system. The webhook handler will need to accept the requests and perform the action with the contents in the request.

To sign up for Webhooks, you’ll need to subscribe to an event of your choosing and provide the address of your webhook handler for each event you wish to subscribe to. An example of a webhook handler address is:

https://webhook.site/a5a6d378-3e6b-4ca2-a1ae-4c32dc168504

Webhook Format

Webhook can contain one or multiple events depending on your system's needs. It will always consist of limited event payload information that you can then use to retrieve additional information about that event. To version events, maintain security, and limit payload size, the event payload does not return the object itself, such as an order or shipment definition - just the IDs. 

For instance, when you receive a Webhook for an order-update event you can use the order ID in that payload to then make a GET request to the Order API and retrieve the full order data.

Webhook Fields

Webhook objects may contain the following basic information to describe events. Depending on the event type, the Webhook payload may also contain an Order ID, your internal Order ID, or a shipment ID, and responseDescription may vary or provide additional details about an event.

• RequestId - An identifier used to track API requests across different services.

• EventType - The type of event that occurred, such as order-creation or order-update.

• MetaData - This is a list of key:value string pairs which varies depending on what information is being provided.

• SubscriberId - This is a unique identifier of the entity the order belongs to.

• Description - Contains the message that describes the event. For example, if the order was created successfully or failed to be created.

• ResponseCode - 200 for success, 4xx or 5xx in case of failure 

Webhook Topics

Webhooks are organized by topics, which are buckets of one or more notifications associated with a particular event/object such as orders or shipments. The table below lists some of the most common notifications and identifies the events that trigger them.

Webhook Configuration

To configure your Webhooks, once you’re logged in, go to the left side Admin panel and click on Webhooks. From there, you can subscribe to an event by creating your first Webhook.

Once you click on the Create a Webhook button, you’ll land on a page that provides you with the following fields that need to be configured:

• Events - allows you to Select an Event you wish to subscribe to by choosing a specific event from a drop-down list of events:

  • OrderCreation,

  • OrderUpdate,

  • ShipmentCreated, or

  • ShipmentUpdate. 

• Callback Method - allows you to choose a method for sending a Webhook

• Callback URL - allows you to enter the address of your Webhook handler

• Custom Headers - allows you to add any custom headers you need / you can use this for authenticating against your Webhook handler

Please note that, when creating the Webhook, you can add multiple events to a single Webhook by adding them from the events drop-down list.

In case you wish to edit your Webhook configuration at a later time, you can just hit Save or simply Save & Activate right away if no further editing is needed.

Webhook Customization

You also have the option to customize the Webhook payload so the values you receive are matching your system needs. First you need to configure and publish a webhook. Then you need to access the edit mode by clicking on Webhook ID and Edit button:

Once you're in Edit mode, click on Create Customization:

You'll be presented with a UI where you can transform the Webhook payload according to your needs. You'll need a couple of things:

1. Input String - The original Webhook payload that our system is sending for a specific event

2. Code Snippet - A transformation code snippet that will tell our system how to transform the payload

Once you provide the Code Snippet and the Input String, you'll be able to check how your customized Webhook payload will look like by hitting the Test Code Snippet button. Let's see an example below where we transformed IsSuccessful to EventStatus, ExternalOrderId to InternalOrderId, EventType to OrderEvent,etc.:

Once you're satisfied with how your customized Webhook payload looks like, just hit Save and customization is done.

Test Webhooks

You can test your Webhook subscriptions, by triggering the Test button on the Create Webhook page before you hit the Save & Activate button. Even if you go straight to Save & Activate, the test will be automatically triggered.

Continue to Merchant Notifications Guide OR Vendor Notifications Guide