POST request to it for every subscribed event.
Webhooks are currently available to pilot customers. Contact your Nexus account manager to enable delivery for your workspace.
How it works
1
Enable the Webhooks extension
A user with the Extensions Manage permission switches on Webhooks under Settings → Extensions → Webhooks.
2
Create an endpoint
A user with the Webhooks Manage permission adds an HTTPS URL, selects the events to subscribe to, and activates the endpoint.
3
Store the signing secret
Nexus shows the signing secret (
whsec_...) once. Store it securely — you need it to verify every request.4
Receive and verify events
Nexus sends a signed JSON payload to your endpoint. Verify the signature, respond with a
2xx status, and process the event asynchronously.Permissions
Access is controlled by permissions that can be added to any role under Settings → Roles.webhooks:manage includes webhooks:view. By default, only the Workspace Admin role has both.
Event payload
Every request body uses the same envelope. Payloads are intentionally thin: they contain identifiers only, never names, emails or other personal data. Use the Nexus API or MCP to fetch the current state of the record.Top-level fields
Actor
Channel attribution is being expanded. Today many changes are reported as
system even when a user made them. Do not build business logic on channel yet.Event types
Deleted events contain only the ID of the deleted record. When a record is deleted together with related records, each related record may produce its own event.
HTTP request
Nexus sends aPOST request with Content-Type: application/json and these headers, following the Standard Webhooks specification:
Verifying signatures
The signature is an HMAC-SHA256 over{webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded part of your secret after whsec_. Always verify against the raw request body and reject timestamps older than 5 minutes.
Secret rotation
When you generate a new secret, the previous one stays valid for 24 hours. During that window each request carries two signatures, so you can deploy the new secret without downtime. A manager can end the overlap early.Responding and retries
- Respond with a
2xxstatus within 5 seconds. Do heavy processing in a background job. - Redirects are not followed and count as failures.
- Timeouts, network errors, unresolvable hosts,
408,429and5xxresponses are retried after 1 min, 5 min, 30 min, 2 h and 6 h (6 attempts in total). After that the delivery is marked dead. - Other
4xxresponses fail immediately without retry. - Events can arrive more than once and out of order. Deduplicate by
webhook-idand usetimestampfor ordering.
Endpoint health and alerts
When an endpoint becomes Failing, every Webhooks manager in the workspace receives an email in their profile language (at most once per endpoint per 24 hours). Paused endpoints receive no new deliveries until a manager clicks Reactivate. Test events never affect endpoint health.
Logs and replay
Under Settings → Extensions → Webhooks you find:- Event catalog — all event types with example payloads.
- Recorded events — every event recorded for your workspace, with payload inspection.
- Deliveries — every attempt with status, response code, duration and attempts. Managers can replay finished deliveries.
Endpoint requirements
- HTTPS on port 443 with a valid certificate.
- Publicly reachable; private, loopback and internal addresses are rejected.
- Only active endpoints receive events, and only while the Webhooks extension is on.
Best practices
Verify every request
Reject requests with invalid signatures or stale timestamps.
Respond fast
Acknowledge with
2xx immediately and process in a queue.Be idempotent
Store processed
webhook-ids and skip duplicates.Fetch fresh data
Payloads contain IDs only. Load the current record via the API.