Webhook security

Webhooks can be securely validated using the Calibre-HMAC-SHA56-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.

Ruby Example post '/payload' do request.body.rewind payload_body = request.body.read verify_signature(payload_body) # Safely use the JSON end def verify_signature(payload_body) signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), ENV['SECRET_TOKEN'], payload_body) return halt 500, "Signatures didn't match!" unless ActiveSupport::SecurityUtils.secure_compare(signature, request.env['Calibre-HMAC-SHA56-Signature']) end

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.