Webhooks for New Leads

A webhook sends each new lead from your chat channels, such as website chat, Messenger and Instagram, to another app as soon as it is captured: your CRM, Zapier, Make, n8n or your own code. KnowStack makes a signed HTTPS POST with the lead's contact details and the conversation up to that moment.

Add a webhook

1. Copy the webhook address from the app that should receive the leads. It must start with https://.
2. In KnowStack, open Settings, select 'Integrations' and go to 'Send leads to your CRM'.
3. Under 'Add a webhook', enter a 'Name' you will recognise, paste the 'Webhook address' and click 'Add webhook'.
4. Copy the signing secret that appears. It starts with whsec_ and is shown only once. Then click 'I've saved it'.
5. Open the webhook's menu and click 'Send test'. The result appears straight away and in the 'Delivery log'.

Only leads captured after you add the webhook are sent; earlier leads stay in KnowStack. You can add several webhooks, and each new lead goes to every active one.

When requests are sent

Messages written after the lead was created are never sent. A lead.updated request goes out only after lead.created was accepted, and only when a field went from empty to filled.

Request headers

Payload (version 1)

The body is JSON in UTF-8, sent without line breaks and shown formatted here. Values in angle brackets stand for your own: the product name is KnowStack, and the address is the one you sign in at. A lead.created request:

{
  "version": 1,
  "event": "lead.created",
  "deliveryId": "4821",
  "occurredAt": "2026-01-15T10:03:12.000Z",
  "lead": {
    "id": 1375,
    "name": "Anna Novak",
    "email": "[email protected]",
    "phone": null,
    "channel": "web_chat",
    "channelLabel": "Website chat",
    "source": "<product name> · Website chat",
    "question": "Do you have availability next week?",
    "firstPageUrl": "https://example.com/pricing",
    "locale": "en",
    "capturedAt": "2026-01-15T10:02:40.000Z",
    "conversationUrl": "https://<your app address>/dashboard/channels/website-chat?conversation=812"
  },
  "transcript": [
    { "from": "customer", "text": "Hi, do you have availability next week?", "at": "2026-01-15T10:00:05.000Z" },
    { "from": "ai", "text": "Yes, we do. Could I take your email so the team can confirm a time?", "at": "2026-01-15T10:00:09.000Z" },
    { "from": "customer", "text": "Sure, [email protected]", "at": "2026-01-15T10:02:40.000Z" }
  ],
  "transcriptIncomplete": false
}

A lead.updated body has the same version, event, deliveryId, occurredAt and lead fields, with the lead's current values. Instead of the conversation it carries changed, the list of fields filled in since the last request, for example ["phone"].

Verify the signature

1. Read the raw request body before parsing it as JSON.
2. Join the X-Webhook-Timestamp value, a dot and the raw body.
3. Compute the HMAC-SHA256 of that text with your signing secret, the whole value including whsec_, and write it in hex.
4. Compare v1= plus that hex with X-Webhook-Signature, using a constant-time comparison.
5. Reject the request if the timestamp is more than 5 minutes away from your clock. This stops an old request from being replayed.

An example for Node.js with Express:

const crypto = require('crypto');
const express = require('express');

const SECRET = process.env.LEAD_WEBHOOK_SECRET; // whsec_...
const app = express();

// Keep the body raw: the signature covers the exact bytes that were sent.
app.post('/leads', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.get('X-Webhook-Timestamp') || '';
  const received = req.get('X-Webhook-Signature') || '';
  const expected = 'v1=' + crypto
    .createHmac('sha256', SECRET)
    .update(timestamp + '.' + req.body)
    .digest('hex');

  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
  const valid = received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!fresh || !valid) return res.status(401).end();

  const body = JSON.parse(req.body);
  // req.get('X-Webhook-Delivery') identifies the delivery: skip it if you
  // have already handled it.
  console.log(body.event, body.lead.id);
  res.status(204).end();
});

app.listen(3000);

To check your code: the secret whsec_test, the timestamp 1761559200 and the body {"a":1} give the signature v1=ed347bcd87edf5b36afc10e41346740621d7f3c26b13ee1a4cc1eb7cddd0786f.

Responses and retries

Answer within 10 seconds, or the attempt counts as a timeout. Only the first 64 KB of your response is read. Respond first and do slow work afterwards.

When a webhook needs attention

While a webhook shows 'Needs attention' or 'Paused', new leads wait in the queue instead of being lost. When a webhook stops, the people who manage users get one alert in the notification bell, and on Telegram if they connected it. Fix the receiving app or correct the address with 'Edit', or click 'Resume' if the address was right. Sending picks up again, starting with the leads that waited.

'Delivery log' in the webhook's menu shows the last 50 requests with their result and response code. Click 'Retry' on a failed one to send it again with the same delivery id. In the 'Leads' tab of each chat channel, a marker shows whether a lead reached your CRM; for a lead that wasn't sent, choose 'Send to CRM again' in its row menu. If leads keep failing while a webhook stays active, its row says 'Recent deliveries failed' and the people who manage users get an alert, at most once a day.

Signing secret

If the secret has leaked, choose 'New signing secret' in the webhook's menu. The old secret stops working at once, so put the new one into the receiving app straight away.