Events

Signed webhooks

Push mention, keyword, alert, project, integration, and webhook events to your infrastructure with durable retries and HMAC verification.

Create an endpoint

Create workspace-wide or project-scoped endpoints from Dashboard → Developer or with create_webhook. URLs must use HTTPS and resolve to public addresses; credentials, fragments, nonstandard ports, localhost, and private networks are rejected.

Secret shown once

The whsec_ signing secret is encrypted at rest and returned only when created or rotated. Keep it in a server-side secret manager.

Payload

{
  "id": "evt_...",
  "type": "mention.created",
  "apiVersion": "2026-09-03",
  "createdAt": "2026-09-03T09:30:00.000Z",
  "projectId": "...",
  "data": { }
}

The event ID remains stable across retries and can be used for receiver-side deduplication.

Verify the signature

Read the raw request body before JSON parsing. Join webhook-id, webhook-timestamp, and the raw body with periods, then compare a Base64 HMAC-SHA256 digest with the v1 value in webhook-signature.

Node.js

const signed = [webhookId, timestamp, rawBody].join(".");
const expected = crypto
  .createHmac("sha256", process.env.CHATTERBEAM_WEBHOOK_SECRET)
  .update(signed)
  .digest("base64");

Reject stale timestamps

A valid signature alone does not stop replay of a captured request. Enforce a short timestamp tolerance.

Delivery lifecycle

Any 2xx response succeeds. Failures retry up to eight times with increasing delays from one minute to 48 hours. Requests time out after ten seconds, redirects are not followed, and twenty consecutive failures disable an endpoint. Delivery history is replayable for 30 days.

Event types

mention.createdmention.updatedmention.status_changedmention.marked_irrelevantkeyword.createdkeyword.updatedkeyword.deletedkeyword_group.createdkeyword_group.updatedkeyword_group.deletedalert.createdalert.updatedalert.deletedalert.deliveredproject.createdproject.updatedproject.public_dashboard_updatedproject.archivedproject.restoredintegration.connectedintegration.disconnectedintegration.sync_completedintegration.sync_failedwebhook.test