Configuring outbound webhooks

Webhooks push real-time event data to your server whenever something happens in AIsoule.

Creating a webhook

1. Go to Settings → Webhooks
2. Click "New Webhook"
3. Configure:
   • Name — Descriptive name (e.g., "CRM Sync", "Order Notifications")
   • URL — Your server endpoint (must be HTTPS)
   • Events — Which events to subscribe to
4. Click Save

A secret key is auto-generated for signature verification.

Selecting events

Choose which events trigger the webhook:

Select only the events you need — fewer events = less load on your server.

Testing your webhook

1. After creating, click "Test"
2. A sample payload is sent to your URL
3. Verify your server responds with HTTP 200
4. Check the response in the webhook logs

Webhook logs

View delivery history:

1. Open the webhook
2. Click "Logs" or "Recent Deliveries"
3. See:
   • Timestamp
   • Event type
   • Response status (200, 500, timeout)
   • Response time

Signature verification

Every webhook includes an X-Webhook-Signature header containing an HMAC-SHA256 signature.

Verify in your code:

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return expected === signature;
}

Retry behavior

If your endpoint fails (non-200 response or timeout):

• Retry 1: After 10 seconds
• Retry 2: After 60 seconds
• Retry 3: After 5 minutes
• After 3 failures: webhook is marked as "failing"

Disabling a webhook

1. Open the webhook
2. Toggle "Active" to OFF
3. Events will no longer be sent (but the configuration is preserved)

Tips

1. Respond quickly — Return 200 immediately, process async
2. Handle duplicates — Same event may arrive twice (use event ID)
3. Monitor failures — Check webhook status weekly
4. Use the secret — Always verify signatures in production
5. Start with one event — Add more as needed