Webhooks


Webhooks can be added on a per site basis in order to get Snapshot metrics, URLs to screenshots, videos and other media out of Calibre.

Adding a webhook manually

  • Navigate to the site in Calibre, then Settings → Integrations → Add Webhook
  • Paste in the destination URL (Data will be delivered as application/json via HTTP POST)
  • Check the “Snapshot” event checkbox
  • Click “Save notification”
  • Webhooks are delivered after a snapshot has been completed

Adding a webhook pragmatically

Webhooks and other integrations can be managed pragmatically using the Node.js API. See the Integrations page for more information.

Example JSON output

A webhook will be JSON (application/json) delivered via HTTP POST to an endpoint of your choosing. Here is an example of the output:

Security & Verification

Webhooks can be securely validated using the Calibre-HMAC-SHA256-Signature header. This header should be used in order to establish that the incoming request originates from Calibre.

This header is formulated by supplying a shared secret with Calibre.

Setting a shared secret

  1. Navigate to the webhook in question. (Site → Settings → Integrations)
  2. Use the automatically generated secret, or create your own.
  3. Press Save Notification.

Verifing the secret

Calibre uses HMAC cryptographic hash signature for verification purposes.

In order to verify the Calibre request, you will need to use the shared secret that you supplied earlier.

Notes:

  • In the examples above we have set the original secret as an environment variable. Never commit the secret to source control.
  • Comparing hashes using the equal comparison operator (==) is not advised as it cannot protect against timing attacks.

We recommend that you use a third party webhook test service, or enable verbose logging in order to verify the webhooks are delivered in the format as expected.