Errors & sandbox

Stable error codes, webhook signature verification, and test-mode keys.

Error envelope

Every error response uses the same envelope. error.code is stable and machine-readable; error.message is human-readable and may change. Validation errors carry error.details mapping field → messages.

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": { "contact_id": ["Required"] }
  }
}

Error catalog

Sandbox / test keys

brivio_sk_test_… keys authenticate against a paired sandbox organization, provisioned automatically on first use. Data is fully isolated from your live organization, fiscal identifiers stay empty, and no ANAF/e-Factura submissions or other external side effects ever fire. Webhooks are environment- scoped too: endpoints registered with a test key only receive test events.

Verify webhook signatures

Deliveries follow Standard Webhooks: each request carries webhook-id, webhook-timestamp (unix seconds) and webhook-signature, a space-separated list of v1,<base64> tokens — HMAC-SHA256 over {id}.{timestamp}.{rawBody}, one token per active secret while a secret is being rotated. The timestamp is inside the MAC, so a captured delivery cannot be replayed with a new timestamp:

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

function verifyBrivioWebhook(
  rawBody: string,
  id: string,        // "webhook-id" header
  timestamp: string, // "webhook-timestamp" header, unix seconds
  signature: string, // "webhook-signature" header, "v1,<base64> [v1,<base64>]"
  secret: string,    // "whsec_..."
): boolean {
  const ts = Number(timestamp);
  if (!Number.isInteger(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false; // 5 min window
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = Buffer.from(
    "v1," + createHmac("sha256", key).update(`${id}.${ts}.${rawBody}`, "utf8").digest("base64"),
  );
  return signature.split(" ").some((token) => {
    const actual = Buffer.from(token);
    return actual.length === expected.length && timingSafeEqual(actual, expected);
  });
}

Or use verifyWebhookSignature() from the @brivio-ro/sdk package, which implements the same check.