Webhooks

Receive automatic notifications when events occur in your store.

Configuration

Configure your webhook endpoint in the Dashboard:

1. Go to Settings → Webhooks
2. Add your endpoint URL
3. Select the events you want to receive
4. Save the configuration

Request format

POST /your-webhook-endpoint
Content-Type: application/json
X-Neuroon-Signature: sha256=abc123...
X-Neuroon-Event: search.completed

{
  "id": "evt_123abc",
  "type": "search.completed",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    // Event-specific data
  }
}

Verify signature

Validate that webhooks come from Neuroon:

const crypto = require('crypto');

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

  return `sha256=${expected}` === signature;
}

// In your endpoint
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-neuroon-signature'];
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process event
  res.status(200).send('OK');
});

Retries

If your endpoint doesn't respond with 2xx:

Attempt	Wait
1	Immediate
2	5 minutes
3	30 minutes
4	2 hours
5	24 hours

After 5 failed attempts, the webhook is deactivated.

Best practices

1. Respond quickly - Return 200 OK immediately
2. Process async - Use queues for heavy processing
3. Idempotency - The same event may arrive multiple times
4. Logging - Keep logs for debugging

app.post('/webhook', async (req, res) => {
  // Respond immediately
  res.status(200).send('OK');

  // Process in background
  queue.add('process-webhook', req.body);
});