Overview

Every webhook will be sent as a POST to the webhook subscription URL.

Example of the webhook payload:

POST https://your-url.com/receiver
Headers: Signature="payload=signature-to-verify"

{
  event_id: 1000, # unique integer across all webhooks, useful for dedup
  event_type: "profile_updated", # one of the key from the examples below
  source_id: 3, # id of the resource that generated the webhook
  data: {...}, # one of the payload from the examples below 
}

🚧

Reliability for safety-critical integrations

Although we endeavour to provide a reliable service, we do not currently offer a delivery or timeliness guarantee on webhook delivery. If your integration is safety-critical we recommend employing redundant approaches, such as regular API polling, to ensure you receive notification of all important changes.

Verification

It's strongly recommended to verify that Lookout originated the webhook.

To do that, we create a signature hash and add it to the header under the key Signature and the value is payload=a-hash-generated.

The signature is created with the webhook subscription key, shared with you when the subscription is created in Lookout.

The value is an HMAC hex digest of the combined sha256 digest, the shared key, and the payload.

If the payload signature matches your recreated signature, then it can be trusted that it came from us.

In Ruby, the above is equivalent to the following:

digest = OpenSSL::Digest.new("sha256")
signature = OpenSSL::HMAC.hexdigest(digest, your_shared_key, payload)

Outbound IP addresses

Webhook payloads are delivered from a somewhat stable set of IP addresses, which are available via our API at the meta API endpoint.

We make changes to these IP addresses from time to time. We do not recommend allowing by IP address, however if you use these IP ranges we strongly encourage regular monitoring of our API.

Timeouts

Your server should respond to a webhook request with a 2xx response within 20 seconds. After that time the request will count as unsuccessful and the request will be retried. If your integration needs longer than this time to perform its work, we recommend using a queue to perform the work asynchronously.

Retry behaviour

If we fail to connect to your callback URL, we will re-attempt delivery with an exponential backoff. However, if we are able to connect but receive anything other than a successful response (HTTP 200 - 299), to avoid confusion we will not make further attempts.

Deactivation behaviour

Webhook callbacks that haven't produced a successful response in some time will be deactivated, and the company's technical staff members will receive an email notification. In particular, webhooks will be automatically deactivated by the following conditions:

• High-traffic webhooks producing 75 or more errors without success in a 15 minute period
• Any webhook with 20 consecutive delivery failures since the last successful delivery, over at least 24 hours

In this event, if you wish to re-enable such a webhook, you can do so via either the API or the admin console.