Verifying Webhooks

Verify the events that Caption.Ed sends to your webhook endpoints.

It's good practice to verify that any webhooks you receive are really from Caption.Ed. We use webhook signatures to allow you to verify the authenticity of a payload received.

When you create a new Webhook Endpoint you'll be issued with a webhook signing secret.

Every webhook sent from Caption.Ed will contain the following headers:

Captioned-Timestamp: "1893456000"
Captioned-Signature: <SHA256_SIGNATURE>

You can verify the payload by creating your own signature from the timestamp and payload and signing it with your signing secret.

Here is an example in Node.js:

import crypto from 'crypto';

const signingSecret = process.env["CAPTIONED_WEBHOOK_SIGNING_SECRET"]

const verifySignature(request) {
  // Get headers
  const timestamp = request.headers['Captioned-Timestamp']
  const requestSignature =  request.headers['Captioned-Signature']
  
  // Check the headers are present
  if (!timestamp || !requestSignature) return false
  
  // Optionally: Check the timestamp is in your allowable range (e.g. within 1 min)
  
  // Get the raw request body
  const payload = request.body
  
  // Combine the timestamp with the payload to build the signature data
  const signatureData = [timestamp, ".", payload].join("")
  
  // Create a SHA256 HMAC instance with your signingSecret
  const hmac = crypto.createHmac('sha256', signingSecret)
  
  // Create the verification hex
  const verification = hmac.update(signatureData).digest('hex')

  // Check if it matches the header value
  return verification === requestSignature
}