Knock Webhooks

Knock Webhooks

When to Use This Skill

• Setting up Knock outbound webhook handlers
• Debugging x-knock-signature verification failures
• Handling Knock notification message lifecycle events (sent, delivered, bounced, read, link_clicked)
• Reacting to Knock resource changes (workflow.committed, translation.committed, etc.)
• Porting a Stripe-style verifier to Knock and discovering it silently fails (Knock uses milliseconds, Stripe uses seconds)

Verification (core)

Knock signs each webhook with HMAC-SHA256 (base64) and sends a single header:

x-knock-signature: t=,s=

The signed string is ${timestamp_ms}.${raw_body} (period separator). The timestamp is in milliseconds, not seconds — this is an explicit deviation from Stripe. There is no SDK helper (@knocklabs/node and knockapi do not expose an inbound verification method); verify with the standard library.

const crypto = require('crypto');

function verifyKnockSignature(rawBody, header, secret, toleranceMs = 5 * 60 * 1000) {
  if (!header) return false;
  const [tPart, sPart] = header.split(',');
  const timestampMs = tPart?.startsWith('t=') ? tPart.slice(2) : null;
  const signature = sPart?.startsWith('s=') ? sPart.slice(2) : null;
  if (!timestampMs || !signature) return false;

  if (Math.abs(Date.now() - parseInt(timestampMs, 10)) > toleranceMs) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestampMs}.${rawBody}`)
    .digest('base64');

  const a = Buffer.from(signature, 'utf8');
  const b = Buffer.from(expected, 'utf8');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

> For complete handlers with route wiring, event dispatch, and tests, see: > - [examples/express/](examples/express/) > - [examples/nextjs/](examples/nextjs/) > - [examples/fastapi/](examples/fastapi/)

Common Event Types

| Event | Description | |-------|-------------| | message.sent | Message was sent through a channel | | message.delivered | Channel confirmed delivery | | message.delivery_attempted | Delivery attempt was made (success or failure) | | message.undelivered | Channel failed to deliver after retries | | message.bounced | Recipient address bounced | | message.seen | Recipient saw the message in feed/inbox | | message.read | Recipient marked the message as read | | message.archived | Recipient archived the message | | message.interacted | Recipient interacted with the message | | message.link_clicked | Recipient clicked a tracked link | | workflow.committed | Workflow committed to an environment | | translation.committed | Translation committed to an environment |

> For full event reference (23 events across message, workflow, emaillayout, translation, sourceeventaction, partial), see Knock Outbound Webhooks Event Types.

KNOCK_WEBHOOK_SECRET=your_per_endpoint_signing_secret  # From Developers → Webhooks → endpoint detail

# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 knock --path /webhooks/knock

// Generated with: knock-webhooks skill
// https://github.com/hookdeck/webhook-skills