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.

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.

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

You can also 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 and for sandbox applications we send webhooks from and so you will need to whitelist all of these.