Webhooks (Outbound)

Webhooks let SalesOS call your system when something happens (a lead is offered, a ranking is published, a message is dispatched). You give us an HTTPS URL and a secret; we POST a signed JSON payload to it whenever a subscribed event fires.

This page covers outbound webhooks (SalesOS → your endpoint). For sending data into SalesOS, see Activities and API Keys.

Configure a webhook in the Dashboard

Go to Integrations → Webhooks → New Webhook and fill in the form.

Basic

Name (required) — e.g. Notify CRM.
Key — a stable identifier (e.g. notify_crm).
Description — optional.

Events (triggers)

Pick a Category, then select the events that fire this webhook — this is your subscription (see the catalog). Leave it empty for a webhook you only trigger manually (the Test button) or from a workflow.

Destination

Method — POST (default), PUT or PATCH.
Timeout (seconds) — how long we wait for your 2xx (default 30).
URL (required) — your endpoint. Must be https:// and public (internal/loopback hosts are blocked).
Authentication — choose HMAC to sign every delivery, then in Auth Config (JSON) set your secret:
{ "secret": "whsec_your_secret" }
(Other schemes are available: Bearer, API Key, Basic, OAuth2.)

Advanced

Custom Headers (JSON) — extra headers sent with every delivery.
Payload Template (JSON with {{ }} variables) — shapes the envelope data from the event context, e.g. { "id": "{{event.id}}", "type": "{{event.type}}", "to": "{{event.to}}" }.

Template values are interpolated into JSON. Use flat, scalar fields. Injecting a nested object via "{{event.data}}" may not render cleanly today — always check the Preview / send a Test first.

Preview, test & save

The form shows a live Preview (headers + body). Click Save webhook, then use Test Webhook to send a sample delivery and confirm your endpoint receives — and verifies — it.

The envelope

On the event path, every delivery is a single JSON object:

{
  "id": "evt_2KWPBgLlAfxdpx2AI54pPJ85f4W",
  "type": "ranking.weekly.published",
  "version": "1",
  "ts": "2026-06-03T12:00:00.000Z",
  "tenant": "9b1f0c2e-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
  "data": { /* event-specific — see catalog */ }
}

Field	Description
`id`	Unique event id, stable across retries → your idempotency key.
`type`	Event type (see catalog).
`version`	Schema version of `data`. Evolves additively.
`ts`	When the event occurred (ISO 8601, UTC).
`tenant`	Origin tenant (uuid).
`data`	Event-specific payload.

Headers

Header	Description
`X-SalesOS-Event`	Event type — route without parsing the body.
`X-SalesOS-Event-Id`	Equals `id`; stable across retries (idempotency).
`X-SalesOS-Delivery-Id`	Per-attempt id (changes on retry; for debugging).
`X-SalesOS-Timestamp`	Unix seconds — part of the signature (anti-replay).
`X-SalesOS-Tenant`	Origin tenant id.
`X-SalesOS-Signature`	`sha256=<hmac>` — see Verify.

Verify the signature

Always verify the signature before trusting a delivery. Without it, anyone who learns your URL could forge events.

On the event path, the signature covers {id}.{timestamp}.{rawBody} (Standard-Webhooks style), so it authenticates the payload and the timestamp (anti-replay). Recompute the HMAC with your secret, compare in constant time, and reject if the timestamp is more than 300s off.

import crypto from "node:crypto";

// raw = the exact raw request body (do NOT JSON.parse first)
export function verify(req, secret) {
  const id  = req.headers["x-salesos-event-id"];
  const ts  = req.headers["x-salesos-timestamp"];
  const sig = req.headers["x-salesos-signature"]; // "sha256=<hex>"
  const raw = req.rawBody;

  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // replay window

  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(`${id}.${ts}.${raw}`).digest("hex");

  const a = Buffer.from(sig), b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

import hmac, hashlib, time

def verify(headers, raw_body: bytes, secret: str) -> bool:
    event_id = headers["X-SalesOS-Event-Id"]
    ts       = headers["X-SalesOS-Timestamp"]
    sig      = headers["X-SalesOS-Signature"]  # "sha256=<hex>"

    if abs(time.time() - int(ts)) > 300:        # replay window
        return False

    msg = f"{event_id}.{ts}.{raw_body.decode()}".encode()
    expected = "sha256=" + hmac.new(secret.encode(), msg, hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig, expected)

Test deliveries (the “Test Webhook” button) and legacy workflow triggers currently use a simpler scheme: the body is the raw rendered template (not the envelope) and the signature header is X-Signature: <prefix><hmac(body)> — without the id.timestamp. prefix, so it has no anti-replay. Prefer the event path above for production.

Event catalog

`type`	When it fires	`data`
`lead.offer_created`	A lead is offered to a broker	lead/opportunity payload
`lead.accepted`	A broker accepts a lead	lead/opportunity payload
`lead.offer_expired`	An offer expires before acceptance	lead/opportunity payload
`mission.completed`	A mission is completed	mission payload
`ranking.weekly.published`	Weekly ranking is published (scheduled)	leaderboard (rows by email)
`ranking.consolidated.published`	Consolidated ranking is published	leaderboard (rows by email)
`message.dispatch`	A message is dispatched to a user/group	`{ to, m }`
`notification.push.dispatch`	A push is dispatched to a user/group	`{ to, n }`
`checkin.confirmed`	A collaborator checks in and becomes eligible for leads	`{ checkin_id, type, queue_eligible, location_id, location_name, shift, shift_expires_at, user }`
`checkin.shift_closed`	The configured shift ended — the collaborator leaves the queue	`{ checkin_id, queue_eligible, reason, user }`
`checkin.checked_out`	The collaborator clocked out — leaves the queue	`{ checkin_id, type, queue_eligible, user }`

Check-in: the three moments a queue changes

Eligibility changes at exactly three moments, and each has its own event. If you route leads by who is on duty, subscribe to all three — taking only the first leaves people enabled forever.

Event	Meaning for your queue
`checkin.confirmed`	Enable. Duty or home office, created successfully
`checkin.shift_closed`	Disable. The configured shift ended
`checkin.checked_out`	Disable. The person clocked out

A check-in that does not make someone eligible never reaches you. Delivering it would tell you to enable somebody who cannot receive leads.

Expiry by inactivity — no signal from the app for four hours — is a safety net, not a rule, and deliberately does not reach you. It still notifies the collaborator.

Expiry is evaluated by a job that runs every 15 minutes, so checkin.shift_closed can arrive up to 15 minutes after the shift’s closing time. If your side enforces a hard cutoff, use the shift end from the Check-in API rather than waiting for the event.

Every check-in event carries a user block — the identity of whoever entered or left the queue, resolved on our side so you can recognize the person without any prior identity agreement. Example data for checkin.confirmed:

{
  "checkin_id": "5f0c…",
  "type": "duty",
  "queue_eligible": true,
  "location_id": "a1b2…",
  "location_name": "Stand Jardim Alameda",
  "shift": "manha",
  "shift_expires_at": "2026-08-17T15:00:00Z",
  "user": {
    "id": "3c3d…",
    "name": "Maria Santos",
    "email": "maria@empresa.com",
    "cpf": "52998224725"
  }
}

user.cpf may be null — not every collaborator has a document on file; fall back to user.email. Fields that do not exist at the moment of the event (e.g. shift on a clock-out) arrive as null, never dropped from the schema.

Example data for ranking.weekly.published:

{
  "p": { "type": "weekly", "label": "Semana 23/2026", "start": "2026-05-25", "end": "2026-05-31" },
  "org_unit": null,
  "totals": { "users": 843, "points": 1820400, "missions": 5120 },
  "rows": [
    { "rank": 1, "delta": 2, "email": "maria@loja.com", "points": 4820, "missions": 37, "org_unit": "ou_12" }
  ]
}

Recipients are keyed by email — names and ids are not sent; enrich on your side if needed.

Reliability

Respond fast. Return a 2xx status quickly (before heavy processing) to acknowledge receipt.

Your response	What SalesOS does
`2xx`	Marks the delivery completed. No retry.
`4xx` (400, 401, 422…)	Treated as a permanent rejection. No retry (except `429`, which respects backoff).
`5xx` / timeout / connection error	Retried with exponential backoff (`2^n` minutes, up to 5 attempts), then dead-lettered.

Idempotency. The same event may be delivered more than once (retries). Deduplicate on X-SalesOS-Event-Id — it stays the same across retries.

Failed deliveries land in the Deliveries panel (Dashboard → Integrations → Webhooks) where you can inspect status, attempts and the last error, and resend from the dead-letter queue.

​Webhooks (Outbound)

​Configure a webhook in the Dashboard

​The envelope

​Headers

​Verify the signature

​Event catalog

​Check-in: the three moments a queue changes

​Reliability

Webhooks (Outbound)

Configure a webhook in the Dashboard

The envelope

Headers

Verify the signature

Event catalog

Check-in: the three moments a queue changes

Reliability