Register Webhooks

Webhooks eliminate the need to poll — Spectra POSTs events to your endpoint as they happen.

Prerequisites

API key with scope webhooks:manage
An HTTPS endpoint that accepts POST requests

Register a webhook

curl -X POST "https://api.spectradiag.com/api/v1/webhooks" \
  -H "Authorization: Bearer spk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myapp.com/spectra-webhook",
    "events": ["order.created", "order.shipped", "inventory.sold"]
  }'

Response includes a secret — save it now, you cannot retrieve it later:

{
  "success": true,
  "data": {
    "id": 42,
    "url": "https://myapp.com/spectra-webhook",
    "events": ["order.created", "order.shipped", "inventory.sold"],
    "secret": "f9a3d7b2e8c1..."
  }
}

Your endpoint

A minimal webhook handler (Express.js):

import express from 'express';
import crypto from 'crypto';
 
const app = express();
const SECRET = process.env.SPECTRA_WEBHOOK_SECRET;
 
app.post('/spectra-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.header('X-Webhook-Signature');
  const event = req.header('X-Webhook-Event');
 
  // Verify the signature
  const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).end();
  }
 
  // Ack immediately
  res.status(200).end();
 
  // Process in background
  const payload = JSON.parse(req.body.toString());
  console.log(`Received ${event}:`, payload.data);
 
  // Your handler logic here — e.g. sync to your database
});
 
app.listen(3000);

Available events

See the full event list in Getting Started.

Or subscribe to everything with ["*"]:

{
  "url": "https://myapp.com/all-events",
  "events": ["*"]
}

Check delivery history

curl "https://api.spectradiag.com/api/v1/webhooks/42/deliveries" \
  -H "Authorization: Bearer spk_live_xxx"

Returns the last 50 deliveries with HTTP status, response body, and errors — useful for debugging why your endpoint isn't receiving events.

Unregister

curl -X DELETE "https://api.spectradiag.com/api/v1/webhooks/42" \
  -H "Authorization: Bearer spk_live_xxx"

Retry policy

Spectra is fire-and-forget — if your endpoint is down or returns a non-2xx status, the event is NOT retried. Keep your endpoint:

Fast — respond within 5 seconds
Resilient — queue events for background processing rather than doing work inline
Idempotent — handle duplicate events gracefully

For critical events (e.g. order processing), run a periodic reconciliation job that polls the API for any orders you might have missed.

Track Shipments Features Overview