Introduction

This guide provides an in-depth understanding of how webhooks function within the context of Product Ledger and Marketplace apps. Although the mechanism is uniform for both, the distinction lies in the objects associated with the webhooks and the resulting output.

Fields

A webhook comprises four essential fields:

1. Endpoint URL: This is the URL to which the object JSON is sent via an HTTP Post.
2. Object: Specifies the object type sent to the endpoint URL as JSON. The webhook triggers only if the object and action are true.
3. Action: Indicates the action on the object triggering the webhook (Created or Updated). The webhook fires only if both object and action are true.
4. Shared Secret: An optional token for authenticating requests sent to the endpoint URL.

Adding Webhooks

In the Ledger, navigate to the admin section and select the Webhooks menu item. Click "Create Webhook," fill in the desired fields, and click to save. If an error occurs, simply delete the webhook and create a new one. Multiple webhooks for the same object/action combination are possible for various endpoints.

Authentication

To authenticate requests sent to the endpoint URL, input a Shared Secret when creating the webhook. Requests are signed using the shared secret and the request body. The signature is added as the "x-signature" header. A SHA1 digest is calculated using the shared secret and the JSON-stringified body of the request.

var signature = req.headers['x-signature'];
var digest = crypto
    .createHmac('sha1', settings.sharedSecret)
    .update(new Buffer(JSON.stringify(req.body), 'utf-8'))
    .digest('hex');

if (signature === digest) {
    // your logic
}

Miscellaneous Information

• Webhooks fire only once, and there is no guaranteed delivery. If the endpoint is inaccessible, the webhook will not retry.
• Webhooks are sent in JSON format via HTTP Post.
• There is no set limit to the number of webhooks that can be added.
• It is strongly recommended that the Endpoint URL uses SSL.

Product Ledger - Actions and Objects

Actions

• Created: Sends the created object to the endpoint URL after the object is created.
• Updated: Sends the updated object to the endpoint URL after the object is updated.

Objects

• Order
• Contact
• Account
• User
• Channel
• Product
• Channel Product
• WorkOrder
• Campaign

Feel free to reach out if you have any questions or need further assistance on your webhook integration journey. Happy coding! 🚀