Webhooks

Webhooks notify your server when selected events occur. Register an HTTPS endpoint, subscribe only to the events you need, and validate each delivery before processing it. The signing header and exact signature format must be confirmed against a real delivery before production use.

Available event types

The frontend currently lists bot.created, bot.deleted, chat.started, chat.completed, lead.created, subscription.created, subscription.updated, user.created, and knowledge.uploaded. Treat the authenticated GET /webhooks/events response as the source of truth for the events enabled in your environment.

Create a webhook with a destination URL and one or more event names. The secret is returned when the endpoint is created; save it securely at that time. The dashboard includes delivery logs and controls to enable, disable, or remove an endpoint.

Verify before processing

The snippets below illustrate raw-body HMAC-SHA256 verification using the X-Webhook-Signature header and a sha256=<hex> value. The repository's frontend does not specify the server's exact signing algorithm, header encoding, or retry contract. These code examples are intentionally provisional: confirm the header, digest, prefix, and encoding from a current first-party webhook specification or test delivery, then adapt the verifier before deploying it.

Read the raw request bytes before JSON parsing, use a timing-safe comparison, reject invalid signatures, and make event processing idempotent. Never log the signing secret or accept a request solely because it contains a plausible event name.

Register an endpoint

curl --request POST "$PRIMEWEBKIT_API_URL/webhooks" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $PRIMEWEBKIT_ACCESS_TOKEN" \
  --data '{"url":"https://example.com/hooks/primewebkit","events":["lead.created","chat.completed"]}'

Node.js / Express: raw-body signature check (verify protocol first)

import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const app = express();
const secret = process.env.PRIMEWEBKIT_WEBHOOK_SECRET;
if (!secret) throw new Error("PRIMEWEBKIT_WEBHOOK_SECRET is required");

app.post("/hooks/primewebkit", express.raw({ type: "application/json" }), (req, res) => {
  const supplied = req.header("X-Webhook-Signature") ?? "";
  const expected = `sha256=${createHmac("sha256", secret).update(req.body).digest("hex")}`;
  const suppliedBytes = Buffer.from(supplied);
  const expectedBytes = Buffer.from(expected);
  const valid = suppliedBytes.length === expectedBytes.length && timingSafeEqual(suppliedBytes, expectedBytes);
  if (!valid) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString("utf8"));
  // Validate the event shape and process it idempotently.
  return res.sendStatus(200);
});

Python / Flask: raw-body signature check (verify protocol first)

import hashlib
import hmac
import json
import os
from flask import Flask, abort, request

app = Flask(__name__)
secret = os.environ["PRIMEWEBKIT_WEBHOOK_SECRET"].encode("utf-8")

@app.post("/hooks/primewebkit")
def receive_webhook():
    raw_body = request.get_data(cache=True)
    supplied = request.headers.get("X-Webhook-Signature", "")
    expected = "sha256=" + hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(supplied, expected):
        abort(401)

    event = json.loads(raw_body)
    # Validate the event shape and process it idempotently.
    return "", 200

Frequently asked questions

Which webhook events are available?

The frontend lists bot.created, bot.deleted, chat.started, chat.completed, lead.created, subscription.created, subscription.updated, user.created, and knowledge.uploaded. Query GET /webhooks/events for the authoritative list in your environment.

Can I use the example signature code as-is?

Not until the current signing algorithm, header format, and digest encoding are confirmed. The examples show HMAC-SHA256 with a sha256= hexadecimal prefix as an explicitly provisional pattern.

Where do I review failed deliveries?

Open the Webhooks area in the dashboard and inspect the delivery log for the endpoint. The available frontend includes a per-webhook logs endpoint.