Webhooks

Subscribe to outbound events and receive HTTP POST notifications when shifts are filled, credentials expire, payroll runs are submitted, and more.

Event Types

Event	Trigger
`shift_posted`	A new shift is created
`shift_filled`	Assigned staff count reaches required staffing for the shift
`credential_expired`	A credential is marked expired (API), license-on-file is past expiry (watchdog), or related flows
`timesheet_approved`	A shift work log / timesheet is approved
`lead_qualified`	A CRM lead’s status becomes `qualified`
`payroll_completed`	A payroll run is approved and submitted to the payroll provider (`status` moves to processing — see payload)
`staff_onboarded`	A new staff member record is created via the staff API
`agent_run.pending_approval`	A headless agent run paused awaiting approval (resolve via `/api/approvals/:id/{approve,reject}`)
`agent_run.completed`	A headless agent run finished successfully
`agent_run.failed`	A headless agent run errored or was rejected by an approver
`*`	Subscribe to all domain events (does not change test behavior — see below)

Create a Subscription

curl -X POST https://api.nexspace365.com/api/webhooks \
  -H "Authorization: Bearer nex_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Alerts",
    "url": "https://your-app.com/webhooks/nexspace",
    "events": ["shift_filled", "credential_expired"]
  }'

Internal operators with cross-org access should also pass orgUnitId as a query parameter or JSON field targeting the customer org unit (team). The response includes a signingSecret (shown once):

{
  "id": 42,
  "name": "Production Alerts",
  "url": "https://your-app.com/webhooks/nexspace",
  "events": ["shift_filled", "credential_expired"],
  "signingSecret": "whsec_aBcDeFgHiJkLmNoPqRsTuVwXyZ...",
  "isActive": true
}

Payload Format

Wire JSON body (also stored on delivery rows):

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "shift_filled",
  "data": {
    "shiftId": 456,
    "facilityId": 12,
    "assignedStaffIds": [101, 102]
  },
  "occurredAt": "2026-05-10T14:30:00.000Z"
}

data fields vary by event (for example payroll_completed includes payrollRunId, externalPayrollId, and status).

Signature Verification

Every webhook includes an X-NexSpace-Signature header for verification:

X-NexSpace-Signature: sha256=abc123def456...

The event name is repeated in X-NexSpace-Event. Verify the body with HMAC-SHA256:

import crypto from 'crypto';

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = crypto.createHmac('sha256', secret).update(body).digest('hex');
  return `sha256=${expected}` === signature;
}

import hmac
import hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return f"sha256={expected}" == signature

Retry Policy

A delivery is considered successful when your endpoint responds with a 2xx status. Any other status (or a connection error/timeout) schedules a retry on a fixed exponential backoff — the initial send plus up to 5 retries (6 attempts total):

Attempt	When
1	immediately, on the triggering event
2	~30 seconds after attempt 1
3	~2 minutes after attempt 2
4	~15 minutes after attempt 3
5	~1 hour after attempt 4
6	~6 hours after attempt 5

Retries are processed by a background job that ticks about once a minute, so nextRetryAt on a delivery row is the earliest a re-attempt will fire, not an exact time. Each attempt is recorded on the delivery (status code, response body, error) and visible via Delivery Inspection. Every retry request also carries an X-NexSpace-Retry header with the attempt number.

Auto-disable (dead-letter)

If the final (6th) attempt still fails, the subscription is automatically disabled (isActive: false) so a broken endpoint stops consuming retries. When this happens NexSpace:

stamps the reason and last error on the subscription’s metadata (disabledReason: "max_retries_exceeded", disabledAt, lastError),
writes an audit-log entry (WEBHOOK_SUBSCRIPTION_DISABLED), and
notifies the subscription’s creator in-app so a human can act.

Once your endpoint is healthy again, re-enable the subscription via PATCH /api/webhooks/{id} with { "isActive": true } (or from Settings → Platform webhooks). New events resume delivery immediately; NexSpace does not replay events that occurred while the subscription was disabled.

Delivery Inspection

View recent delivery attempts for a subscription:

curl https://api.nexspace365.com/api/webhooks/42 \
  -H "Authorization: Bearer nex_live_YOUR_KEY"

Returns the subscription detail plus the last 25 delivery attempts with status codes, response bodies, and error messages. The Settings UI exposes the same data under Platform webhooks → Deliveries.

Test Events

POST /api/webhooks/{id}/test sends a type: test signed POST to that subscription’s URL only, even if the subscription does not list test or * — use this to verify connectivity.

curl -X POST https://api.nexspace365.com/api/webhooks/42/test \
  -H "Authorization: Bearer nex_live_YOUR_KEY"

Or via CLI:

nexspace webhooks test --id 42
nexspace fixtures webhook-test --webhook-id 42
nexspace events trigger --webhook-id 42

Local debugging with the CLI

nexspace events listen starts a local HTTP receiver, creates a temporary subscription, verifies X-NexSpace-Signature when signingSecret is returned, and prints deliveries as JSONL. Cloud API hosts cannot reach 127.0.0.1 — tunnel first:

ngrok http 8787
nexspace events listen --port 8787 --forward-url https://xxxx.ngrok-free.app/hooks --max-events 5

Point NEXSPACE_BASE_URL at a local API if you do not need a tunnel. See CLI Commands → Webhooks & events.

Getting Started

Core Concepts

Integrations

Reference

Webhooks

Webhooks

Event Types

Create a Subscription

Payload Format

Signature Verification

Retry Policy

Auto-disable (dead-letter)

Delivery Inspection

Test Events

Local debugging with the CLI

​Webhooks

​Event Types

​Create a Subscription

​Payload Format

​Signature Verification

​Retry Policy

​Auto-disable (dead-letter)

​Delivery Inspection

​Test Events

​Local debugging with the CLI

Webhooks

Event Types

Create a Subscription

Payload Format

Signature Verification

Retry Policy

Auto-disable (dead-letter)

Delivery Inspection

Test Events

Local debugging with the CLI