Webhooks

Real-time event notifications for your Solid# account

Event Types

HMAC

SHA-256 Signatures

Auto-Retry

<1s

Delivery Time

What are 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.

Real-time updates

Get notified instantly when payments succeed, subscriptions renew, inventory runs low, or AI agents complete tasks. Build reactive, event-driven applications.

Setting Up Webhooks

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
Register in Dashboard
Go to Settings → Webhooks in your Solid dashboard and add your endpoint URL. Select which events you want to receive.
3
Test your webhook
Use the dashboard to send test events and verify your endpoint is receiving and processing webhooks correctly.

Available Events

Subscribe to any combination of these events to receive notifications:

Inventory Events (Jake AI)

inventory.reserved

Stock reserved for order — Jake AI monitors

inventory.confirmed

Payment confirmed, reservation locked

inventory.released

Order canceled, stock released back

inventory.expired

Reservation timeout expired

inventory.backorder_created

Out of stock, backorder created — Jake AI handles

inventory.low_stock

Stock below threshold — Jake AI auto-reorders

Order Events

order.created

New order placed

order.paid

Payment confirmed for order

order.canceled

Order canceled by customer or system

order.fulfilled

Order shipped with tracking number

Payment Link Events

payment_link.paid

Payment link successfully paid

payment_link.expired

Payment link expired without payment

Affiliate Events (Annie AI)

affiliate.commission_triggered

New commission earned — Annie AI processes payout

affiliate.payout_completed

Commission paid to affiliate

CRM Events (AI-Powered)

crm.contact.created

New contact added to CRM

crm.contact.updated

Contact information updated

crm.deal.created

New sales deal created

crm.deal.stage_changed

Deal moved to new stage in pipeline

crm.deal.closed

Deal won or lost

Example Webhook Payload

All webhook events have the same structure:

JSON Payload

{
  "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
  }
}

Verifying Webhook Signatures

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.

Security Critical

Never process webhooks without verifying the signature. Attackers could send fake webhook requests to your endpoint.

Signature Verification Code

Node.js

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
  res.status(400).send('Invalid signature');
}

Best Practices

Respond quickly

Return 200 within 5 seconds. Process heavy work asynchronously.

Handle duplicates

Webhooks may be delivered more than once. Use the event ID to deduplicate.

Use HTTPS only

Webhook endpoints must use HTTPS for security. HTTP is not supported.

Subscribe selectively

Only subscribe to events you need to reduce unnecessary traffic.

Retry Logic

If your endpoint does not return a 2xx status code, Solid will automatically retry:

1st retryafter 5 minutes

2nd retryafter 30 minutes

3rd retryafter 2 hours

After 3 failed attempts, the webhook delivery is marked as failed and you will receive an email notification.

Testing Webhooks

Dashboard Test Events

Go to Settings → Webhooks and click “Send Test Event” to trigger a sample webhook to your endpoint.

Test Mode

Use test API keys to trigger real events (like creating payments) that will send webhooks without affecting production data.

Local Development

Use tools like ngrok or localtunnel to expose your local server to the internet and receive webhooks during development.

Start Receiving Events

Set up your first webhook endpoint and build reactive, event-driven applications with Solid#.

API Reference SDK Libraries CLI Docs