Skip to main content
Webhooks let Nexus notify your systems the moment something happens in your workspace — a candidate is created, an application moves to a new stage, or a form is submitted. Instead of polling the Nexus API, you register an HTTPS endpoint and Nexus sends a signed 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.
When Webhooks is switched off, all active endpoints are deactivated. Switching it back on does not reactivate them automatically.

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 a POST 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 2xx status within 5 seconds. Do heavy processing in a background job.
  • Redirects are not followed and count as failures.
  • Timeouts, network errors, unresolvable hosts, 408, 429 and 5xx responses 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 4xx responses fail immediately without retry.
  • Events can arrive more than once and out of order. Deduplicate by webhook-id and use timestamp for 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.