Webhooks API

Overview

Webhooks allow you to receive HTTP POST notifications when events occur in your NexusDB instance. Use them to trigger workflows, sync data, or send alerts.

Create a Webhook

POST /api/v1/webhooks

{
  "url": "https://your-app.com/webhook",
  "events": ["document.created", "document.updated"],
  "collection": "orders",
  "secret": "whsec_your_signing_secret"
}

Event Types

Webhook Payload

{
  "id": "evt_abc123",
  "type": "document.created",
  "collection": "orders",
  "timestamp": "2024-03-15T14:22:00Z",
  "data": {
    "document": {
      "id": "doc_xyz789",
      "title": "Order #1234",
      "total": 299.99
    }
  }
}

Verifying Signatures

Every webhook request includes an X-NexusDB-Signature header. Verify it to ensure the request is genuine:

const crypto = require("crypto");

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

Retry Policy

Failed deliveries are retried with exponential backoff:

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

After 5 failed attempts, the webhook is automatically disabled. Re-enable it from the admin dashboard.