Webhooks

Webhooks are used to immediately notify your server of events that take place in the Lean ecosystem. These are especially useful for events that take place on your front end through the Lean SDK or events that take place asynchronously. Once you receive an event on your server, you can process and act on it as you need.

Webhook retry policy

We consider a webhook as having been successfully delivered when we receive a success status code (200) from the webhook URL you specified in your application dashboard.

If we receive any other status code or do not receive a response within 10 seconds, we will start retrying. We take an exponential back off approach to resending webhooks until we receive a successful response sending retries 1, 2, 5, 10, 60, and 180 minutes after the initial webhook was sent.

Webhook security

It is important to ensure that webhooks sent to your Webhook URL truly came from Lean. Without such verification a bad actor can send a fake request to your Webhook URL and potentially cause your system to react as if the request came from Lean.

Subsequently Lean provides two methods for you to secure your webhooks and ensure they're coming directly from us.

❗️

Ensure your webhooks are secured!

For securing the webhook messages sent by Lean, the following security checks are highly recommended to be implemented in your integration:

• Check our webhook signature with Webhook Secret Token
• Whitelist webhook IP
• Always validate the Lean App Token

Request signing and signatures

If you inspect the headers sent with our webhooks, you’ll see a lean-signature with a value that begins with “sha512=“.

This is the signature — a hash-based message authentication code (HMAC) which was constructed by using SHA-512 as the message digest algorithm and your “webhook secret” as the shared secret key to hash the webhook body. Your “webhook secret” can be found in the Integration section of the developer portal.

📘

Generate signatures without deserializing the response-payload

The best way to ensure that framework dependencies don't contaminate the response-body is to ensure that all signatures are generated on buffers and not on deserialized objects.

Express.js is notorious for contaminating the response-body which cause signature mismatch.

Always make sure that your not deserializing your body response-body to ensure successful signature matching

Upon receiving the webhook you can compute the signature by computing the HMAC yourself using the webhook body and your webhook secret and then comparing it with the value of the lean-signature header. When you perform your hash calculations, ensure that you use the raw payload of the webhook body to avoid altering the values within the payload prior to calculating the hash. With this you can ensure that the webhook you received came from Lean and nobody else.

IP Whitelisting

Static IP whitelisting

You can configure your server or endpoint to exclusively accept POST requests from the IP Addresses we use to send webhooks. For production applications we send all webhooks from 193.123.78.188 and for sandbox applications we send webhooks from 193.123.89.181 and so you will need to whitelist these addresses if you choose to whitelist static IP addresses.

DNS-based lookup whitelisting

We also use a DNS Lookup mechanism so that, you can implement human-readable domain-names rather than static IP addresses for better integration robustness. This approach offers flexibility and convenience. You will no longer need to update your implementation when IP addresses change. Instead, you can rely on the DNS system to automatically resolve the correct IP address.

To implement DNS-based whitelisting, you will need to follow these steps:

1. Resolve the domain name provided to obtain the corresponding IP address. DNS resolution is a process that translates domain names (like google.com) into IP addresses (like 172.217.22.14). This can be achieved by using DNS lookup functions provided by programming languages or using command-line tools like nslookup or dig. The DNS for production is webhooks.leantech.me and for sandbox is webhooks.sandbox.leantech.me
2. Once the IP address is obtained, you should configure your system or network security settings to allow incoming traffic only from that specific IP address. This step ensures that only requests originating from the resolved IP address are permitted while blocking all others. Please note that many cloud providers do not allow you to whitelist a DNS directly so you will first need to resolve the DNS to the IP address it points to using step 1.