Alert Authentication and Security

Validating Signatures from Leaf

Keeping your webhook secure is essential to ensure that only Leaf sends requests to your endpoint. To help with this, Leaf uses signatures to verify every request.

Here’s how it works:

  • Signatures and Secrets: Each webhook request is signed using HMAC with SHA-256. The secret key you set up during the alert’s configuration is used to generate the signature.

  • What You Should Do: Use the X-Leaf-Signature header in the request to verify the signature. This ensures the request is genuine and untampered. The digest added to the X-Leaf-Signature header is encoded in base 64.

  • Handling the Request Body: Always read the request body as raw bytes before verifying the signature. The signed content is a compact JSON string without extra line breaks or spaces (other than spaces after ":" and ",").

By following these steps, you’ll ensure that your application only processes requests sent by Leaf.

info

Using an X-CompanyName-Signature header is a common method of securing webhooks and is used by many companies including Twilio and Slack.

Here is an example on how to verify the request in your webhook:

import hmac
import base64
import json
payload = 'alert_payload'
# Sign the request body received with your secret
expected_sig = hmac.digest(msg=bytes(json.dumps(payload), 'utf-8'),
key=bytes('your secret key', 'utf-8'),
digest='sha256')
# Decode the base-64 encoded X-Leaf-Signature header that was sent in the event header
sig_header = "x-leaf-signature-in-header"
request_sig = base64.b64decode(sig_header)
# Compare both
hmac.compare_digest(expected_sig, request_sig)

The value alert_payload corresponds to the payload of the alerts.

For example, if you need to authenticate a created field, the alert_payload will be:

{
"source": "REST",
"leafUserId": "the id of the file owner",
"fieldId": "the id of the created field",
"timestamp": "yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'",
"type": "fieldCreated"
}

Webhooks and IP Addresses

Leaf uses a cloud architecture to provide services, and as such, does not have a fixed range of IP addresses that issue webhooks.

When designing your network architecture, you may wish to have one set of servers and a load balancer in a DMZ that receive webhook requests from Leaf, and then proxy those requests to your private network.

Edit this page