Quickstart

Fifteen minutes, end to end. You need a URL Custral can reach over the public internet and workspace admin access.

Stand up an endpoint

Anything that answers POST with a 2xx will do. Using the TypeScript SDK, the receiver is three lines:

import express from "express";
import {Custral} from "@custral/sdk";

const custral = new Custral({webhookSecret: process.env.CUSTRAL_WEBHOOK_SECRET!});
const app = express();

custral.on("record.created", async (event) => {
  console.log("New record", event.data.recordId);
});

// The raw body parser is required: verification needs the exact bytes.
app.post("/hooks/custral", express.raw({type: "application/json"}), custral.webhooks.express());

app.listen(3000);

Mount express.raw({type: "application/json"}) on the webhook route. A JSON-parsed body cannot be verified, because re-serializing it does not reproduce the bytes that were signed.

Expose it

In development, a tunnel is the quickest route:

ngrok http 3000

Custral refuses localhost, private and link-local IP addresses, and any scheme other than http or https. See What Custral will and will not call.

Open Settings → Developers → Webhooks, choose Add webhook, paste the URL, and tick the events you want.You can also ask the assistant, or any MCP client holding a key with the webhooks:manage scope:

Register a webhook at https://abc123.ngrok.io/hooks/custral for record.created and record.updated.

See Managing subscriptions for both paths in full.

Copy the signing secret

Creating the endpoint returns a whsec_… secret once. Put it in your environment as CUSTRAL_WEBHOOK_SECRET before you close the dialog.

Lost it? Nothing can retrieve it. Rotate the secret to get a new one, and update your environment at the same time.

Fire a real event

Create a record on any object in the workspace. Within a second or two your handler should log its id.Nothing arrived? Open the endpoint in settings and read its delivery log: every attempt is recorded with the HTTP status your server returned. Start at Troubleshooting.

Verifying without the SDK

The signature is a Stripe-style HMAC, so it is a handful of lines in any language. The full algorithm and the reasoning behind each step is on Verifying signatures.

import crypto from "node:crypto";

function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const timestamp = Number(parts.t);
  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Getting started

Building a receiver

Event reference

Operations

Verifying without the SDK

What’s next

Event catalog

Delivery and retries

​Verifying without the SDK

​What’s next

Event catalog

Delivery and retries

Verifying without the SDK

What’s next