Webhooks

A webhook tells your system about something that happened in your Knock account. You give Knock an HTTPS URL and the event types you want, and Knock sends a POST request to that URL every time one of those events occurs: a contact books a meeting, a meeting moves, an enrichment request finishes.

Webhooks or pollingCopy Anchor Link

• Use webhooks to react to events: create a CRM task when a meeting is booked, update a calendar when it moves, start a job when enrichment results are ready. Knock sends you each event, so you don't spend rate limit on requests that find nothing new.
• Use polling to read or backfill data: GET /v1/meetings and GET /v1/enrichment-requests/{enrichRequestId} return the full current state, including everything that happened before you created a webhook.

Most integrations use both. A webhook says that something changed and carries the main fields; the API holds the full record. For example, enrichment_request.completed tells you a request is final, and you then read its results with GET /v1/enrichment-requests/{enrichRequestId}.

Keep a slow poll as a safety net for anything critical: webhooks are delivered at least once, but your endpoint can be down for longer than Knock keeps retrying (see Delivery and retries).

How webhooks workCopy Anchor Link

A webhook is one URL and the event types it receives, with its own id, an optional name, an optional secret token and a status: active or paused.

• Several event types per webhook. One webhook can receive any of the event types: list them in its events, and change the list at any time. Branch on the body's type to tell them apart.
• One webhook per URL. A URL can belong to only one of your webhooks: a second create with the same URL gets 409.
• Several URLs per event type. The same event type can go to several webhooks. Each one gets its own delivery of the event, with the same event id, and the knock-webhook-id header says which webhook it's for.
• Up to 50 webhooks per account, paused ones included. See Limits.
• One secret token per webhook. It's optional. You choose it, and Knock sends it as is in the knock-webhook-token header of every delivery to that webhook, so your receiver can check that the request came from Knock. See Verify each request.
• Pause without deleting. A paused webhook gets nothing until you set it back to active. Pausing drops every delivery not sent yet, retries included. See Pause and resume a webhook.
• At least once, in any order. The same event can arrive more than once, and events can arrive out of order. See Delivery and retries.
• Answer fast. Knock waits 5 seconds for your answer, doesn't follow redirects and never reads the response body: only the status code counts, and Retry-After on a 429 or 503.

Verify each requestCopy Anchor Link

Anyone who learns your URL can send it a request, so your endpoint must check that each one came from Knock. Knock uses a secret token, the same way Telegram's Bot API does:

1. You choose a long random value and set it as the webhook's secretToken, when you create the webhook or later with PATCH /v1/webhooks/{webhookId}.
2. Knock sends it back, exactly as you set it, in the knock-webhook-token header of every delivery to that webhook.
3. Your receiver compares the header with the value it expects, in constant time, and answers 401 if they differ.

Knock doesn't add any other proof to a delivery, so the token is the whole check. It proves the sender knows your token, but it doesn't detect a changed body or a replayed request, and it travels with every request. Treat it like a password: keep it out of source code and logs, and replace it if it's ever exposed. Knock only delivers over HTTPS, so the header is encrypted on the way. See Verify webhooks for the check in full and for rotating the token.

EndpointsCopy Anchor Link

The webhooks API is on the same host as the rest of the Knock API, under https://app.knock-ai.com/v1/webhooks.

Listing and reading webhooks, event types and stats need a key with the Admin, Editor, Viewer, CRM Admin or AI Manager role: an Enrichment API key can't. Creating, changing, deleting, pinging, testing a URL and reading a secret token need a key with the Admin role. See Authentication. Errors for every route are listed under Manage webhooks.

These routes have no per-account rate limit: only the per-IP limit applies, 3,000 requests per minute by default. On top of it, you can ping each webhook once every 10 seconds, and your account can test a URL once every 10 seconds. Over any of them, a call gets 429 with a Retry-After header. The deliveries Knock sends to your endpoints never count. See Rate limits.

QuickstartCopy Anchor Link

export KNOCK_WEBHOOK_TOKEN=$(openssl rand -hex 32)

curl -X POST https://app.knock-ai.com/v1/webhooks \
  -H "x-api-key: $KNOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "name": "CRM sync",
  "url": "https://hooks.yourcompany.com/webhooks/knock",
  "events": ["meeting.booked", "meeting.rescheduled"],
  "status": "paused",
  "secretToken": "$KNOCK_WEBHOOK_TOKEN"
}
EOF

{
  "id": "1c9e5b7a-3f2d-4e8a-b6c1-7d0f2a4e9b35",
  "name": "CRM sync",
  "url": "https://hooks.yourcompany.com/webhooks/knock",
  "events": ["meeting.booked", "meeting.rescheduled"],
  "status": "paused",
  "hasSecretToken": true,
  "createdAt": "2026-11-02T09:30:00.000Z"
}

npm install express

import { createHash, timingSafeEqual } from 'node:crypto';
import express from 'express';

const expected = createHash('sha256').update(process.env.KNOCK_WEBHOOK_TOKEN).digest();

function tokenMatches(received) {
  if (typeof received !== 'string') return false;
  const actual = createHash('sha256').update(received).digest();
  return timingSafeEqual(actual, expected);
}

// Event IDs already handled. Use your database in production.
const handled = new Set();

const app = express();

app.post('/webhooks/knock', express.json(), (req, res) => {
  if (!tokenMatches(req.get('knock-webhook-token'))) {
    return res.sendStatus(401);
  }

  const event = req.body;
  res.sendStatus(200);

  if (handled.has(event.id)) return;

  handleEvent(event)
    // Mark the event handled only once its work succeeded, so a duplicate delivery retries a failure.
    .then(() => handled.add(event.id))
    .catch((error) => console.error(`Failed to handle event ${event.id}`, error));
});

async function handleEvent(event) {
  switch (event.type) {
    case 'webhook.ping':
      console.log('Ping for webhook', event.data.webhookId);
      break;
    case 'meeting.booked':
      console.log('Meeting booked', event.data.meetingId, event.data.startAt);
      break;
    default:
      console.log('Ignoring event type', event.type);
  }
}

app.listen(3000, () => console.log('Listening on port 3000'));

curl -X POST https://app.knock-ai.com/v1/webhooks/1c9e5b7a-3f2d-4e8a-b6c1-7d0f2a4e9b35/ping \
  -H "x-api-key: $KNOCK_API_KEY"

{
  "eventId": "5e2b9c4a-7d1f-4a3e-8b6c-0f9d2e1a3c7b",
  "delivered": true,
  "statusCode": 200,
  "errorCode": null,
  "durationMs": 184,
  "retryAfterSeconds": 10
}

EventsCopy Anchor Link

The webhook events reference shows the envelope every event shares, the headers, each event's data fields and an example. New event types are announced in the changelog.

Next stepsCopy Anchor Link