API ReferenceWebhooks

Webhooks Admin

Webhooks send real-time HTTP notifications to your server when specific events occur in Nucleus.

Supported Events

EventTrigger
pipeline.completeA data ingest job finishes processing
report.generatedA scheduled or on-demand report is ready
alert.triggeredA metric crosses a configured threshold

Configuration

Webhooks are configured in Settings > API Keys.

  1. Click Add Webhook.
  2. Enter the target URL (must be HTTPS).
  3. Select which events to subscribe to.
  4. Click Save.

Payload Format

Webhook payloads are sent as POST requests with a JSON body:

{
  "event": "pipeline.complete",
  "timestamp": "2026-05-16T14:30:00Z",
  "data": {
    "pipeline": "stc",
    "records_processed": 45230,
    "date": "2026-05-16"
  }
}

The data field varies by event type.

Verification

Each webhook request includes a signature header for verification:

X-Nucleus-Signature: sha256=abc123...

Compute an HMAC-SHA256 of the request body using your API key as the secret. Compare it to the signature header to verify the request came from Nucleus.

Retry Policy

If your endpoint returns a non-2xx status code, Nucleus retries the webhook up to 3 times with exponential backoff (1 minute, 5 minutes, 30 minutes).

Webhooks are best-effort. For critical workflows, use the API to poll for updates as a fallback.

Partner APIError Codes