Webhooks

Receive provider webhooks through Chronicle with automatic signature verification and deduplication.

Installnpm install @chronicle-labs/sdk

SDK generation in progress - until published, Node 18+ fetch works with no extra dependencies.

Endpoints

Method	Path	Status
`POST`	`/v1/webhooks/{source_id}`	Beta
`HEAD`	`/v1/webhooks/{source_id}`	Beta

Signature verification

Chronicle verifies provider signatures when a webhook_secret is configured on the source. Set the secret when you register the source via POST /v1/sources, or update it later. Each tenant's sources maintain their own independent secrets.

Supported signature schemes: HMAC-SHA1 (providers like Intercom) and HMAC-SHA256 (providers like Stripe and GitHub). Specify the scheme with the signature_scheme field during source registration. Defaults to hmac-sha256.

When a webhook arrives, Chronicle resolves the tenant from the source's registration and verifies against the stored secret - no environment variables required.

Verify signatures in your app

If you proxy webhooks through your own server before forwarding to Chronicle, verify the signature yourself.

Node

import crypto from "node:crypto";

export function verifySignature(rawBody, signatureHeader, secret) {
  const expected = `sha256=${crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex")}`;
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader || ""),
  );
}

Response

JSON

{
  "received": true,
  "event_ids": ["evt_01J8WNEQ2NWY4G7EJAZ9M8MXXV"],
  "message": "Processed 1 event(s)"
}

Security checklist

Verify signature against the raw request body.
Reject stale signatures using provider timestamp windows.
Use HTTPS only.
Rotate webhook secrets periodically.
Monitor repeated signature failures.