Webhooks API: operation events and signatures

• These routes require a full-account API key. A selected-database key receives 403 KEY_SCOPE_DENIED. See API keys.
• API access requires a Pro or Business plan.

​

Events

​

Payload

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "event": "backup.succeeded",
  "createdAt": "2026-10-14T09:02:00.000Z",
  "data": {
    "operationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "databaseId": "550e8400-e29b-41d4-a716-446655440000",
    "databaseName": "my-app",
    "status": "succeeded",
    "stage": "completed",
    "progress": 100,
    "error": null
  }
}

​

Request headers

​

Verify the signature

1. Build the signed string: the DBHost-Timestamp value, a ., then the raw request body exactly as received.
2. Compute HMAC-SHA256 over that string. Use the full secret, including the whsec_ prefix, as the key.
3. Hex-encode the digest, prefix it with v1=, and compare it to DBHost-Signature in constant time.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyDbhostWebhook(rawBody, headers, secret) {
  const timestamp = headers["dbhost-timestamp"];
  const signature = headers["dbhost-signature"] ?? "";
  const expected =
    "v1=" +
    createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestamp));
  return a.length === b.length && timingSafeEqual(a, b) && ageSeconds <= 300;
}

​

Delivery and retries

• A 2xx response within 10 seconds counts as delivered. Redirects are not followed and count as a failure.
• A failed delivery is retried up to five attempts in total, with growing delays (about 30 seconds, then 1, 2 and 4 minutes, plus jitter).
• A successful delivery resets the endpoint’s consecutiveFailures to 0.
• After a delivery has used all attempts, DBHost disables the endpoint if it has 10 or more consecutive failed attempts. Its enabled becomes false and disabledAt is set. Rotating the secret enables it again.

​

Endpoint URL rules

• The URL must be an absolute https:// URL without a username or password.
• localhost, *.localhost, *.local and *.internal hostnames are rejected.
• The hostname must resolve, and every address must be public. Private, loopback, link-local, carrier-grade NAT, multicast and documentation ranges are rejected. DBHost checks this again on every delivery.
• Any #fragment is removed.

​

List endpoints

GET /api/v1/webhooks
Authorization: Bearer <api-key>

{
  "data": [
    {
      "id": "d4e5f6a7-0000-4000-8000-000000000003",
      "databaseId": null,
      "url": "https://hooks.example.com/dbhost",
      "enabled": true,
      "consecutiveFailures": 0,
      "disabledAt": null,
      "createdAt": "2026-10-14T09:00:00.000Z",
      "updatedAt": "2026-10-14T09:00:00.000Z"
    }
  ]
}

​

Create an endpoint

POST /api/v1/webhooks
Authorization: Bearer <api-key>
Content-Type: application/json

{"url":"https://hooks.example.com/dbhost"}

{
  "data": {
    "id": "d4e5f6a7-0000-4000-8000-000000000003",
    "databaseId": null,
    "url": "https://hooks.example.com/dbhost",
    "enabled": true,
    "createdAt": "2026-10-14T09:00:00.000Z",
    "secret": "whsec_<signing-secret>"
  }
}

​

Rotate the signing secret

POST /api/v1/webhooks/{id}/rotate
Authorization: Bearer <api-key>

{
  "message": "Webhook signing secret rotated.",
  "data": {
    "id": "d4e5f6a7-0000-4000-8000-000000000003",
    "databaseId": null,
    "url": "https://hooks.example.com/dbhost",
    "enabled": true,
    "updatedAt": "2026-10-14T10:00:00.000Z",
    "secret": "whsec_<new-signing-secret>"
  }
}

​

Disable an endpoint

DELETE /api/v1/webhooks/{id}
Authorization: Bearer <api-key>

​

Errors