Webhooks

Knit delivers a signed POST to your endpoint whenever something you care about changes state. Webhooks are the intended way to track collections and payouts — polling is a fallback for reconciliation, not a primary integration.

Configure your endpoint

Set your webhook URL and secret in the dashboard under Business → Developer → Webhooks. There is no public API for changing them.

Your endpoint must be:

• Publicly reachable over http:// or https://. Private, loopback, and internal addresses are rejected.
• Fast. Deliveries time out after 10 seconds. Verify the signature, enqueue the work, and return 2xx immediately.
• Idempotent. The same event can arrive more than once.

Verifying the signature

Every delivery carries an X-Signature header: the HMAC-SHA256 of the raw request body, keyed with your webhook secret, hex-encoded.

import crypto from "node:crypto";
 
// `rawBody` must be the unparsed body. Re-serialising the parsed JSON will
// produce a different byte sequence and the signature will not match.
function verify(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
 
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(signatureHeader ?? "", "utf8");
 
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

import hashlib
import hmac
 
def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

Always compare with a constant-time function, and reject the request if the header is missing.

Retries

A delivery counts as failed if your endpoint returns a non-2xx status, times out, or is unreachable. Knit then retries up to 3 times with a fixed backoff:

After the third retry, delivery stops. The attempt history — status code, response body, and failure reason — is visible in the dashboard, where you can also trigger a manual resend.

Near-identical events for the same business within a five-minute window are collapsed into a single delivery, so a duplicated upstream signal does not become two webhooks. That is a safety net, not a guarantee — keep your handler idempotent.

Payload shape

Every payload carries an eventType. Two things vary by event, so check the table before you write your parser:

• Envelope. Most events are wrapped in a top-level body object. Two are not.
• Key casing. Some payloads use snake_case, others camelCase.

A dispatcher that handles both shapes:

app.post("/webhooks/knit", (req, res) => {
  if (!verify(req.rawBody, req.get("X-Signature"), process.env.KNIT_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
 
  // Acknowledge first — the delivery times out after 10 seconds.
  res.sendStatus(200);
 
  const payload = req.body.body ?? req.body;
  enqueue(payload.eventType, payload);
});

Events