Webhooks

Webhooks allow Crucible to push events to your server as they occur, rather than requiring you to poll the API. This is useful for async workflows, batch processing pipelines, and audit logging.

Supported events

completion.finished — Fired when an async completion request is complete

• completion.failed — Fired when a request fails after all retries

usage.threshold_reached — Fired when your account hits 80% and 100% of plan limits

Registering a webhook

Go to Settings → Webhooks in your dashboard and add your endpoint URL. You can register up to 5 webhook endpoints per account on Pro plans.

Verifying webhook payloads

All webhook payloads are signed with a secret unique to your account. Verify the X-Crucible-Signature header on every incoming request to confirm the payload originated from Crucible.

js
import { verifyWebhook } from 'crucible-sdk';
app.post('/webhook', (req, res) => {
  const isValid = verifyWebhook(req.body, req.headers['x-crucible-signature'], process.env.WEBHOOK_SECRET);
  if (!isValid) return res.status(401).send('Invalid signature');
  // Handle event
});

js
import { verifyWebhook } from 'crucible-sdk';
app.post('/webhook', (req, res) => {
  const isValid = verifyWebhook(req.body, req.headers['x-crucible-signature'], process.env.WEBHOOK_SECRET);
  if (!isValid) return res.status(401).send('Invalid signature');
  // Handle event
});

js
import { verifyWebhook } from 'crucible-sdk';
app.post('/webhook', (req, res) => {
  const isValid = verifyWebhook(req.body, req.headers['x-crucible-signature'], process.env.WEBHOOK_SECRET);
  if (!isValid) return res.status(401).send('Invalid signature');
  // Handle event
});