Webhooks & integration security

Verify the X-Corthex-Signature header

Corthex sends an HTTPS POST with a JSON body, Content-Type: application/json, and X-Corthex-Signature: sha256=<hex digest>. The digest is HMAC-SHA256 over the exact body string using the endpoint’s signing secret. Verify the raw bytes before parsing JSON. Use a constant-time comparison after validating the header format.

The signature authenticates the body; it is not a timestamp-based replay check. Persist the event id and make downstream handling idempotent. Never log the signing secret.

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

export function verifyCorthexWebhook(rawBody: string, header: string | null, secret: string) {
  const match = /^sha256=([a-f0-9]{64})$/i.exec(header ?? "");
  if (!match) return false;
  const expected = createHmac("sha256", secret).update(rawBody).digest();
  const received = Buffer.from(match[1], "hex");
  return timingSafeEqual(expected, received);
}

// Read the request body once, before JSON.parse.
const rawBody = await request.text();
const verified = verifyCorthexWebhook(
  rawBody, request.headers.get("X-Corthex-Signature"), signingSecret
);
if (!verified) return new Response("Invalid signature", { status: 401 });
const event = JSON.parse(rawBody);
// Validate the event, deduplicate event.id, then process or enqueue it.

Events and delivery handling

The supported event types are conversation.created, message.created (assistant messages) and lead.captured. Each event has id, type, created_at and a data object. Subscribe only to the events your integration needs; data fields depend on the event type.

Corthex records attempts and retries failed deliveries. Respond within the five-second receiver timeout, safely accept the notification and queue slow downstream work. Use the delivery history to investigate failures. Receiving an event does not grant permission for an unrelated customer action.

Send events out safely and keep organisation data isolated.

Webhook endpoints are configured at the workspace level. Use them to notify your own system about supported activity without repeatedly polling Corthex. Review delivery history when an endpoint is unavailable and fix the receiver before expecting new events to succeed.

• Create an endpoint: Go to Settings → Webhooks, add the HTTPS receiver URL and choose the events your system needs.
• Verify the receiver: Validate incoming requests in your application before performing irreversible work. Record the event identifier so duplicate deliveries can be handled idempotently.
• Monitor delivery: Use the endpoint and delivery list to inspect failures and retries. A successful response from your receiver should be fast; queue slow downstream work separately.
• Rotate access deliberately: Revoke obsolete API keys and remove endpoints that no longer serve a live integration.
• Tenant isolation Every data record is organisation-scoped. Application transactions and database row-level security both enforce this boundary. Public widget boundary The widget uses public embed endpoints for visitor interaction. Keep workspace API keys out of browser code and use the script embed rather than exposing a server token. Secrets Store keys and webhook signing secrets in your server-side secret manager. Never paste them into a client bundle, public repository or support ticket. Visitor data Use only the contact and conversation data necessary for the requested support flow, and configure the widget copy to be transparent about human follow-up.