Webhooks
CRM — Webhooks
Get CRM record changes pushed to your endpoint instead of polling. Internally a
record mutation emits a data.* event; the public webhook
layer fans it out to your subscribed URL as a stable record.* event.
Public events
Defined in the webhook event catalog (webhook/events/webhook-event-catalog.ts):
| Public event | Internal verb | Fires when |
|---|---|---|
record.created | CREATE | A record is created in a CRM object |
record.updated | UPDATE | A record is updated |
record.deleted | DELETE | A record is deleted |
Subscribe by exact name; unknown names are rejected at create time. List them
live at GET /api/v1/webhooks/events.
Manage subscriptions — /api/v1/webhooks
An API key (or admin JWT) owns its subscriptions:
| Method & path | Purpose |
|---|---|
GET /webhooks/events | The public event catalog |
POST /webhooks/subscriptions | Register a target_url (HTTPS) + events[] → returns a signing secret |
GET /webhooks/subscriptions · /:slug | List / get your subscriptions |
DELETE /webhooks/subscriptions/:slug | Delete a subscription |
Delivery & signature
Each delivery carries these headers:
| Header | Value |
|---|---|
X-Corteksa-Event | the public event name (record.created, …) |
X-Corteksa-Delivery | unique delivery id (dedupe on this) |
X-Corteksa-Signature | t=<unixSeconds>,v1=<hmac-sha256> over the raw body |
Verify the v1 HMAC against your secret over the raw body before trusting
the payload, return 200 fast, and work async — non-2xx responses retry
with backoff, so make your handler idempotent. Full walkthrough:
Receive webhooks.
Loop prevention
A write made through an API key or OAuth token is tagged with its source
(sourceApiKeyId / sourceOauthClientId). The fanout won't deliver that event
back to a subscription owned by the same credential — so your own writes don't
trigger your own webhook.
These are Corteksa → your app webhooks. For provider → Corteksa messaging webhooks (WhatsApp/Facebook replies), see Messaging › Webhooks.
Next
- Step-by-step → Receive webhooks
- The events behind them → Events