Webhooks

Receive HTTP notifications when documents are created, updated, or deleted. Webhooks can also be managed from the dashboard.

info

Plan Limits

Free tier: 3 webhooks total, 1 per collection, 2 retries. Pro tier: 50 total, 10 per collection, 5 retries.

POST/v1/db/{ns}/{collection}/_webhooks

curl -X POST https://api.jsondb.cloud/v1/db/default/users/_webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myapp.com/webhooks/users",
    "events": ["document.created", "document.updated"],
    "description": "Sync user changes"
  }'

GET/v1/db/{ns}/{collection}/_webhooks

List all webhooks for a collection.

GET/v1/db/{ns}/{collection}/_webhooks/{id}

Get a webhook and its recent delivery history.

PUT/v1/db/{ns}/{collection}/_webhooks/{id}

Update a webhook's URL, events, or status.

DELETE/v1/db/{ns}/{collection}/_webhooks/{id}

Delete a webhook.

POST/v1/db/{ns}/{collection}/_webhooks/{id}/test

Send a test event to verify your endpoint.

Event Types

Event	Triggered When
`document.created`	A new document is created (POST)
`document.updated`	A document is replaced or patched (PUT/PATCH)
`document.deleted`	A document is deleted (DELETE)

Delivery Payload

Each delivery sends a POST request to your URL with the following JSON body:

{
  "event": "document.created",
  "namespace": "default",
  "collection": "users",
  "documentId": "usr_abc123",
  "document": { "name": "Alice", "email": "[email protected]" },
  "timestamp": "2026-02-24T12:00:00.000Z"
}

Delivery Headers

Header	Description
`X-JsonDB-Event`	Event type (e.g., document.created)
`X-JsonDB-Signature`	HMAC-SHA256 signature: `sha256=...`
`X-JsonDB-Delivery-Id`	Unique delivery ID for deduplication
`X-JsonDB-Timestamp`	ISO 8601 timestamp of the event

Verifying Signatures

To verify a webhook delivery is authentic, compute the HMAC-SHA256 of the raw request body using your webhook secret and compare it with the X-JsonDB-Signature header.

import crypto from "crypto";

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

Retries & Auto-Disable

Failed deliveries are retried with exponential backoff. After 5 consecutive failures, the webhook is automatically disabled. You can re-enable it from the dashboard or API. Free plan allows 2 retries; Pro allows 5.