Webhook Setup

Terms & Conditions

To set up Webhooks, you must enable them for the company account.

Enable Webhooks

To enable webhooks, an admin user must visit the Settings page, navigate to the section entitled Developer access, and select both Enable Webhooks and Enable Developer Options Access.

This enables webhooks for the company and makes the Developer Options page available.

The Developer Options page provides a location in the LeafLink dashboard experience for managing your webhook subscriptions.

After both settings are enabled, the admin must also grant your account access to the Developer Options page.

Settings > Manage Users > Edit Permissions > Can Access Developer Options

The Developer Options page can be accessed through the nav bar on the Settings page.

Settings > Developer Options

Add a Webhook

Visit the Developer Options page.

Settings > Developer Options

1. Click Add Webhook
2. Enter a name and the URL where you will consume the Webhook.
   • Example:
     • Name: Production
     • URL: https://example.com/leaflink/hooks/
3. Select the events you want to subscribe to.
   • NEW & CHANGED ORDERS - order events
   • NEW & CHANGED PRODUCTS - product events
4. Click Add Webhook

Enable Signatures

To secure communication between your application and LeafLink, you should enable webhook request signatures.

Visit the Developer Options page in Settings.

1. Navigate to the Company Webhook Key section
2. Enter your password
3. Click Generate Key (Note: Only users with company Admin permissions can generate a key)

The value in the Webhook Key field will be used to generate the signatures sent with webhook requests. You will need to reference this value when validating the signatures.

Validate Signatures

The signatures will be included in a LL-Signature header.

LeafLink uses the HMAC SHA-256 hashing algorithm and your company webhook key to generate a unique signature for each request.

To validate that the request was sent from LeafLink, calculate the signature using your webhook key and the request body. Then, compare it to the signature provided with the LL-Signature header in the request. If the two signatures match, the request was sent from LeafLink.

Failure Rates

Webhooks with a 100% failure rate for five consecutive days will be automatically deactivated. If this happens to your webhook, your account owner will recieve an email notification. Once the webhook is fixed, you will be able to reactivate it on the Developer Options page.

Examples

Python

import base64
import hashlib
import hmac

key = bytes('webhook key', 'utf-8')
request_body = '{"foo": "bar"}'

signature = base64.b64encode(hmac.new(key, request_body, digestmod=hashlib.sha256).digest())

# compare the calculated signature to the signature provided in the request header
success = signature == request.headers['LL-Signature']

NodeJS

const crypto = require('crypto');

const key = 'webhook key';
const requestBody = '{"foo": "bar"}';

const signature = crypto.createHmac('sha256', key)
                        .update(requestBody)
                        .digest('base64');

// compare the calculated signature to the signature provided in the request header
const success = signature === request.headers['LL-Signature'];

PHP

$key = 'webhook key';
$requestBody = '{"foo": "bar"}';

$signature = base64_encode(hash_hmac('sha256', $requestBody, $key, true));

// compare the calculated signature to the signature provided in the request header
$success = $signature === $request->headers['LL-Signature'];

Ruby

require 'openssl'
require 'base64'

key = 'webhook key'
request_body = '{"foo": "bar"}'

signature = Base64.encode64(OpenSSL::HMAC.digest('sha256', key, request_body))

# compare the calculated signature to the signature provided in the request header
success = signature == request.headers['LL-Signature']

Update a Webhook

1. Click the edit icon at the far right of the row for the webhook you wish to edit
2. Update the name, url, or subscriptions.
3. Click Save

Disable a Webhook

1. Click the edit icon at the far right of the webhook you wish to edit
2. Uncheck the Enabled checkbox
3. Click Save