Set up webhooks

Prerequisites

• knowmind account on Business API or Enterprise
• A reachable HTTPS endpoint under your control (your own API, an n8n webhook node, a Zapier webhook)
• A secure place to store a secret

Steps

1. 1

   Register the webhook in the dashboard

   In the dashboard go to Webhooks, then "Create webhook". Enter the URL (HTTPS is required), pick the events you want, optionally add a description. Click "Create".

   Outcome: knowmind shows the HMAC secret once — copy and store it securely now. Afterwards it cannot be retrieved.

2. 2

   Send a test event

   In the webhook list, click the test button next to the new entry. knowmind sends a webhook of type webhook.test.

   Outcome: Your endpoint's log shows the test request.

3. 3

   Verify the signature

   Every webhook carries X-knowmind-Signature with value sha256=<hex> — the HMAC-SHA256 of the unmodified raw body with your secret as the key. Always verify the signature before processing the body.

   tscopy

   // Node.js / Next.js
   import { createHmac, timingSafeEqual } from "node:crypto";
   
   export function verifyKnowmindSignature(
     body: string,
     header: string,
     secret: string,
   ): boolean {
     const mac = createHmac("sha256", secret).update(body).digest("hex");
     const expected = "sha256=" + mac;
     if (header.length !== expected.length) return false;
     return timingSafeEqual(Buffer.from(header), Buffer.from(expected));
   }

   pythoncopy

   import hmac, hashlib
   
   def verify_knowmind_signature(body: bytes, header: str, secret: str) -> bool:
       mac = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
       expected = "sha256=" + mac
       return hmac.compare_digest(header, expected)

4. 4

   Understand retry behaviour

   knowmind expects HTTP 2xx within 15 seconds. Anything else (timeout, 4xx, 5xx) triggers a retry with exponential backoff: immediately, then after 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours. After six failed attempts the delivery is marked dead. After 20 consecutive failures the entire subscription is disabled.

Verify the result

Troubleshooting