Webhooks

Webhooks tell your system the moment something happens in a SmartContact workspace: a company added, a contact changed, a deal won, a task completed. Every change in SmartContact is recorded together with its event, so events are never lost, and they reach you within about a minute.

Subscribe

Admins can add a webhook in Settings › Webhooks. Integrations subscribe through the API with their key:

POST https://app.smartcontact.online/v1/webhooks
Authorization: Bearer sc_…
Content-Type: application/json

{ "url": "https://example.com/smartcontact-events", "events": ["company.created", "deal.updated"] }

The answer includes a secret, shown only once. Remove the webhook with DELETE /v1/webhooks/{id}, or answer any delivery with 410 Gone. A key only sees and removes its own webhooks, and can only subscribe to events about data its role can read. Plugins declare a webhook URL and events on their version in the developer portal; installing the plugin subscribes them.

What you receive

POST https://example.com/smartcontact-events
Content-Type: application/json
X-SmartContact-Event: deal.updated
X-SmartContact-Delivery: 6a1c…   (the same on every retry: use it to ignore repeats)
X-SmartContact-Signature: t=1792569600,v1=5f2b…

{
  "id": "evt_10423",
  "type": "deal.updated",
  "created_at": "2026-10-21T09:41:07.000Z",
  "workspace_id": "…",
  "data": { "id": "…", "changed": ["stage_id"] },
  "actor_type": "user",
  "api_url": "https://app.smartcontact.online/v1/deals/…"
}

Events carry ids and the names of changed fields, never names, emails or notes. Fetch api_url with your key to get the record as your key is allowed to see it. When you receive contact.erased or company.erased, delete everything you hold about that record: the person asked to be forgotten.

Check the signature

v1 is the hex HMAC-SHA256 of <t>.<raw body> with your secret (a plugin's events use the plugin's signing secret). Refuse it if it doesn't match or t is more than 5 minutes old.

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

function isFromSmartContact(secret, header, rawBody) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const want = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest();
  const got = Buffer.from(parts.v1 ?? "", "hex");
  return got.length === want.length && timingSafeEqual(got, want);
}

Retries and switching off

• Answer with any 2xx within 10 seconds. Redirects are not followed.
• Anything else is retried after 1, 5 and 30 minutes, then 2, 6, 12 and 24 hours, then given up. Admins can see every delivery in Settings › Webhooks.
• After 20 failures in a row the webhook is switched off. It is also switched off if the key that made it is revoked, the plugin is uninstalled or the person leaves.
• Events may arrive more than once, and in rare cases out of order: use X-SmartContact-Delivery and created_at.

Events (33)