Webhooks

The Tidelift Subscription includes a set of webhooks to allow you to integrate with your own systems and take custom actions based on changes within your catalogs.

Note that webhooks are currently provided as an early access feature. If you'd like access, please email support@tidelift.com.

Setting up a Webhook

To set up a webhook:

1. Navigate to Settings
2. Select Integrations 
3. Add a new URL endpoint. This URL must be reachable over the Internet and use HTTPS.
4. Once you have added a webhook, you'll see it in the table along with the signing secret. This signing secret allows you to verify that the message that you have received in your webhook has come from Tidelift and was intended for you.

Event formatting

All webhooks are sent as a JSON payload as an HTTP POST to your url. The format for all is standardized and the following fields are always included

• event_type - this lets you know the type of event being triggered
• org_name - the name of your organization within Tidelift
• catalog_name - the name of the catalog which the event is for
• event_timestamp - when the event occurred, as an iso8601 string
• event_details - a hash with the specific about the event. The fields within this hash will vary depending on the event_type

Along with the body of the event, the HTTP header X-Tidelift-Signature is set with all requests and contains a signature formatted as sha256=signature where signature is calculated by doing a SHA256 based HMAC of the event body with the signing secret from above as the shared secret key. You can find examples of calculating HMAC in a variety of languages in this document.

All webhooks are sent with a 5 second timeout. If you do not respond with a successful HTTP status code (200) within the 5 second window, it will be retried five times with an exponential backoff and then we will not try to send again.

Event types

There are a number of events sent by Tidelift that you might wish to act on from your webhook. These are the events and the event_details that are sent for each

• Test event (test). The details of this event are blank. Note that test events are not retried.
• Catalog task ready for review (task_ready). These are triggered by a new catalog task being ready for review. The event_details include
  • requested_releases: a list of hashes for each package being request (platform, name, version)
  • requester_email: email address of the user requesting the releases (can be null)
  • project_name: name of the project triggering the request (can be null)

   

• Catalog request approved (request_approved). These are triggered by a catalog task being approved.  The event_details include
  • requested_releases: a list of hashes for each package being request (platform, name, version)
  • requester_email: email address of the user who requested the releases (can be null)
  • project_name: name of the project triggering the request (can be null)
  • reviewer: Name of the person who reviewed the request (can be null)
  • reviewer_email: Email of the person who reviewed the request (can be null)
  • reviewer_notes: notes given by reviewer (can be null)

   

• Catalog request denied (request_denied). These are triggered by a catalog task being denied.  The event_details include
  • requested_releases: a list of hashes for each package being request (platform, name, version)
  • requester_email: email address of the user who requested the releases (can be null)
  • project_name: name of the project triggering the request (can be null)
  • reviewer: Name of the person who reviewed the request (can be null)
  • reviewer_email: Email of the person who reviewed the request (can be null)
  • reviewer_notes: notes given by reviewer (can be null)

   

Example Code

We have published an example of a receiver for Tidelift webhooks that runs as a Google Cloud Function at https://github.com/tidelift/tidelift-webhook-hello-world. This shows how you can look at a webhook payload, verify it, and then just logs a message. But you can see how you would instead do other actions at that point.