• Version: 1.2.0

Webhooks

Webhooks allow you to automatically trigger specified URLs whenever store event occur. So whenever anything in your store is created, updated, or deleted, the webhooks that you have created can pass that information over to the web handlers you specify. Currently, webhooks will trigger on any create, update, or delete event, regardless of the endpoint that caused them.

Key Type Required Unique Details
id String No Yes Automatically populated when you create the webhook.
order Array No No Links to any orders related to this webhook.
created_at String No No Automatically populated when you create the webhook.
updated_at String No No Automatically populated when you modify the webhook.
name String No No A reference name for this webhook.
subject String No No The subject line of the webhook-related email, if any.
url String Yes No The address of the webhook handler. These web handlers must be created outside of the Moltin API system, but can use Moltin API calls.
secret String No No A secret code to match against the web handler to prevent unauthorized access or to indicate individual webhooks.
content_type String Yes No Whether the URL specifies a json array or an x-form-urlencoded page.
create Boolean Yes No Indicate whether you want this webhook to trigger when you create something in the store.
update Boolean Yes No Indicate whether you want this webhook to trigger when you update something in the store.
delete Boolean Yes No Indicate whether you want this webhook to trigger when you delete something in the store.
enabled Boolean Yes No Whether this webhook can be used by the live site (1) or not (0).

Before you can use this (or any endpoint), you need to authenticate to get a bearer token.

This topic will cover the following processes:

Create a Webhook

To create a new webhook for your store, POST the required data to the https://api.molt.in/v1/webhooks endpoint. Every webhook that you create must have data for at least the fields marked Required in the table above. You can put data fields in any order. The URL specified does not need to exist at the time you create the webhook, but you will need to put something there if you want store events to trigger additional actions.

curl -X POST https://api.molt.in/v1/webhooks \
  -H "Authorization: Bearer XXXX" \
  -d "name=New Item Handler" \
  -d "url=https://www.example.com/broken.php" \
  -d "content_type=json" \
  -d "create=1" \
  -d "update=0" \
  -d "delete=0" \
  -d "enabled=1"

This call returns a 201 Created HTML status code and the webhook information for the newly created webhook, including any default or generated values. The object it returns looks like this by default (the data will be different, of course):

{
  "status":true,
  "result":
  {
    "url":"https:\/\/www.example.com\/broken.php",
    "content_type":
    {
      "value":"application\/json",
      "data":
      {
        "key":"json",
        "value":"application\/json"
      }
    },
    "create":
    {
      "value":"Yes",
      "data":
      {
        "key":1,
        "value":"Yes"
      }
    },
    "update":
    {
      "value":"No",
      "data":
      {
        "key":0,
        "value":"No"
      }
    },
    "delete":
    {
      "value":"No",
      "data":
      {
        "key":0,
        "value":"No"
      }
    },
    "enabled":
    {
      "value":"Yes",
      "data":
      {
        "key":1,
        "value":"Yes"
      }
    },
    "id":"7543afd4-0b79-466f-b8f4-af84cb487290"
  }
}

The actions below will return webhook information in this same format.

Retrieve Webhook Information

Once you have created some webhooks, you have two methods to retrieve that information. The first requires that you know the ID string of the webhook that you want, and it returns solely the information for that one webhook. The second returns an array of webhooks that you can specify a maximum number to return and offset the start of the array. Using these options, you can paginate results by increasing the offset of a search by the previous maximum.

Retrieve a Single Webhook by ID String

You can GET information for a single webhook by adding the ID string to the webhooks endpoint. No additional data fields are required.

curl -X GET https://api.molt.in/v1/webhooks/7543afd4-0b79-466f-b8f4-af84cb487290 \
  -H "Authorization: Bearer XXXX"

This returns a 200 OK status code and the webhook information for the specified ID string.

Retrieve a List of All Webhooks

Using the https://api.molt.in/v1/webhooks endpoint, you can return an array that contains all of the webhooks that you have created.

curl -X GET https://api.molt.in/v1/webhooks \
  -H "Authorization: Bearer XXXX"

This returns 200 OK and an array of webhook information, as shown in the Create a Webhook section.

Edit a Webhook

To change one or more values in a webhook, use a PUT call with the webhooks/{ID string} endpoint. You can change most field values through this method, including enabling or disabling a webhook, updating the web handler location, or changing which events trigger it.

curl -X PUT https://api.molt.in/v1/webhooks/7543afd4-0b79-466f-b8f4-af84cb487290 \
  -H "Authorization: Bearer XXXX" \
  -d "update=1"

This returns 201 Created and the updated webhook information.

Delete a Single Webhook

To remove a webhook, use the same webhooks/{ID string} endpoint we used to retrieve a single webhook, except we use the DELETE request method. Note that this will not affect the contents of the webhook URL, just the information stored in the Moltin API.

curl -X DELETE https://api.molt.in/v1/webhooks/7543afd4-0b79-466f-b8f4-af84cb487290 \
  -H "Authorization: Bearer XXXX"

If successful, this call returns 200 OK and the following:

{
	"status":true,
	"message":"Webhook removed successfully"
}