Webhooks API

Overview

A webhook is a method for sending event notifications from one application to another. When something happens in a source system indicated by an event, the webhook transmits an event notification through HTTPS to a specific URL.

You can set up webhooks to receive notifications for order status updates. You’ll receive a notification when the order status changes to FULFILLED or FAILED_PERMANENTLY.

Create and test a webhook

1. Select webhook events

To get a list of notification events you can subscribe to, call the Get webhook events endpoint and retrieve selected event names from data.name fields in the response.

2. Create a webhook

After you’ve selected notification events, create a webhook by calling the Create a webhook endpoint with your workspace ID as the path parameter.

Create a request body for the endpoint as follows:

In events, specify the type of notification events.
In name, assign a custom name to your webhook.
In url, specify the URL of the webhook.

You can also specify optional parameters:

secret, if a secret is used to generate webhook signatures.
active, if you want to make the webhook active immediately after creation.

A sample request body:

JSON

    {
  "events": ["order.status"],
  "name": "My alert for order statuses",
  "url": "https://my.sample.endpoint.com/",
  "secret": "QWZTFnMEXhqZKNmu",
  "active": true
}

3. Test a webhook

To test the created webhook, call the Test a webhook endpoint with your workspace ID and the selected webhook ID as path parameters.

Optionally, you can specify a particular test event in the request body or leave it empty to test for all subscribed events.

Check the response body:

JSON

    {
  "data": {
    "startedAt": "2022-02-18T15:12:18.668452Z",
    "testsRun": 1,
    "testsSucceeded": 1,
    "testsFailed": 0,
    "tests": [ ... ] // A list of tests and their details
  },
  "error": null
}

Determine how many tests have passed or failed by checking the following parameters:

data.testsSucceeded: The total number of successful test requests.
data.testsFailed: The total number of failed test requests.

View webhooks

You can retrieve existing webhooks in one of the following ways:

To get a list of all webhooks, call the Get webhooks endpoint with your workspace ID as the path parameter.
To get a specific webhook, call the Get a webhook endpoint with your workspace ID and the selected webhook ID as path parameters.

Edit a webhook

To change any parameters of an existing webhook, call the Update a webhook endpoint with your workspace ID and the selected webhook ID as path parameters.

Delete a webhook

To delete a webhook, call the Delete a webhook endpoint with your workspace ID and the selected webhook ID as path parameters.

If a webhook is deleted successfully, there will be no response body.