Webhooks

Overview

Webhooks allow you to receive HTTP POST requests to your server when specific events occur in Nurosentrix. This enables real-time integrations without polling the API.

Configuring Webhooks

1. Go to Settings → Webhooks in the dashboard
2. Click "Add Webhook"
3. Enter your endpoint URL
4. Select the events you want to receive
5. Save the webhook

Webhook Events

Server Events

Instance Events

Backup Events

Deployment Events

Webhook Payload

All webhooks send a POST request with a JSON body:

{
  "id": "evt_abc123",
  "type": "instance.deployed",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "instance": {
      "id": "inst_xyz789",
      "name": "production-crm",
      "status": "running",
      "url": "https://crm.example.com"
    }
  }
}

Webhook Headers

Verifying Webhook Signatures

Always verify webhook signatures to ensure requests are from Nurosentrix. The signature is computed using HMAC-SHA256 with your webhook secret.

Python Example

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# In your webhook handler:
signature = request.headers.get("X-Nurosentrix-Signature")
if not verify_signature(request.data, signature, WEBHOOK_SECRET):
    return "Invalid signature", 401

Node.js Example

const crypto = require('crypto');

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

// In your webhook handler:
const signature = req.headers['x-nurosentrix-signature'];
if (!verifySignature(req.rawBody, signature, WEBHOOK_SECRET)) {
  return res.status(401).send('Invalid signature');
}

Retry Policy

If your endpoint returns a non-2xx status code, Nurosentrix will retry the webhook:

• 1st retry: 1 minute after initial attempt
• 2nd retry: 5 minutes after 1st retry
• 3rd retry: 30 minutes after 2nd retry
• 4th retry: 2 hours after 3rd retry
• 5th retry: 24 hours after 4th retry

After 5 failed attempts, the webhook will be marked as failed.

Best Practices

• Respond quickly - Return a 2xx response within 5 seconds
• Process asynchronously - Queue long-running tasks
• Handle duplicates - Use the delivery ID for idempotency
• Verify signatures - Always validate the HMAC signature
• Use HTTPS - Webhook endpoints must use HTTPS

Testing Webhooks

Use the "Test" button in the webhook settings to send a test event to your endpoint. You can also use tools like webhook.site to inspect webhook payloads during development.