Webhooks

SalesOS webhooks send a signed HTTP POST to your endpoint when something happens in your CRM — a lead is created, a deal is won, a customer replies. Register a URL instead of polling the API.

The full reference — the event catalog with a JSON Schema per event, the versioned envelope, signature verification, retries, the delivery log and replay — lives in Developers → Events & webhooks.

Create a webhook

In the app: Settings → API & Webhooks → Webhooks → New webhook, choose the events and copy the signing secret.

Or with the API (API keys need the WEBHOOKS scope):

curl -X POST https://api.salesos.org/v1/webhooks \
  -H "X-API-Key: $SALESOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Warehouse sync",
    "url": "https://your-app.com/webhooks/salesos",
    "events": ["lead.created", "opportunity.stage_changed", "opportunity.won"]
  }'

The response includes secret (shown once). Event types are listed at GET /v1/events/catalog; subscribing to a type that isn't in the catalog is rejected.

Receiving events

{
  "id": "evt_3f9c2a7d1b8e4c60a5d2f1e0b9c8a7d6",
  "type": "opportunity.won",
  "version": 1,
  "occurredAt": "2026-10-01T12:00:00.000Z",
  "organizationId": "org_4k2j9x",
  "data": { "object": "opportunity", "id": "cmopp01", "record": { "…": "…" } }
}

1. Verify X-SalesOS-Signature (t=<unix seconds>,v1=<HMAC-SHA256 of "<t>.<body>">) and reject timestamps more than 5 minutes old.
2. Respond 2xx within 10 seconds; do slow work afterwards.
3. Dedupe on id — retries and replays reuse it.

Failed deliveries are retried with exponential backoff; a webhook whose events keep failing is turned off and its owner notified. Every attempt is kept for 30 days under the webhook's Deliveries, where you can inspect, replay or send a test event.