Webhooks

Webhooks allow you to receive real-time HTTP notifications when events occur in your Solid account. Instead of polling our API for changes, Solid will send you a POST request whenever something important happens.

Setting Up Webhooks

1. 1

   Create an endpoint

   Build an HTTPS endpoint on your server that can receive webhook POST requests. This endpoint should:

   • Accept POST requests
   • Return a 200 status code quickly (within 5 seconds)
   • Verify webhook signatures for security
2. 2

   Register in Dashboard

   Go to Settings → Webhooks in your Solid dashboard and add your endpoint URL. Select which events you want to receive.

3. 3

   Test your webhook

   Use the dashboard to send test events and verify your endpoint is receiving and processing webhooks correctly.

Subscribe to any combination of these events to receive notifications:

All webhook events have the same structure:

{
  "event_type": "inventory.low_stock",
  "company_id": 1,
  "timestamp": "2025-01-23T14:30:00Z",
  "data": {
    "product_id": 42,
    "product_name": "Premium Widget",
    "quantity_available": 5,
    "threshold": 10,
    "location_id": 1,
    "ai_action": "Jake AI auto-reorder triggered"
  },
  "metadata": {
    "agent": "jake",
    "auto_reorder_placed": true,
    "reorder_quantity": 50
  }
}

Solid signs all webhook requests with a signature in the x-solid-signature header. Always verify this signature to ensure the request came from Solid and has not been tampered with.

Signature Verification Code

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

// Usage
const payload = JSON.stringify(req.body);
const signature = req.headers['x-solid-signature'];
const secret = process.env.WEBHOOK_SECRET;

if (verifyWebhookSignature(payload, signature, secret)) {
  // Signature valid - process webhook
  console.log('Webhook verified!');
} else {
  // Invalid signature - reject request
  console.log('Invalid signature');
  res.status(400).send('Invalid signature');
}

Best Practices

• Respond quickly - Return a 200 status code within 5 seconds. Process heavy work asynchronously.
• Handle duplicates - Webhooks may be delivered more than once. Use the event ID to detect and ignore duplicates.
• Use HTTPS only - Webhook endpoints must use HTTPS for security. HTTP is not supported.
• Monitor failures - Check your webhook logs in the dashboard. Solid will retry failed deliveries up to 3 times.
• Subscribe selectively - Only subscribe to events you actually need to reduce unnecessary traffic.

Testing Webhooks

Test your webhook endpoint during development: