Webhooks

Receive lifecycle events from the platform (org/member changes, entitlement grants, sandbox resets, etc.) as signed HTTPS POSTs.

Register an endpoint

Webhook registration is server-to-server, authenticated with your SSO credential (bbas_…) as X-Internal-Key. The webhook is bound to your product — derived from the credential, so you don't (and can't) send a product id. Self-service from this UI is on the roadmap.

curl -X POST https://api.bizbasics.ai/v1/webhooks \
  -H "X-Internal-Key: bbas_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url":         "https://your-product.bizbasics.ai/api/webhooks/bizbasics",
    "event_types": ["org.created", "member.added", "entitlement.granted"]
  }'

The response includes a one-time secret — store it; we never show it again. Sign verification: HMAC-SHA256 over the raw request body, sent as X-Bizbasics-Signature: sha256=<hex>.

Test your endpoint

Once registered, fire a synthetic webhook.test event at your URL to verify reachability + signature handling:

curl -X POST https://api.bizbasics.ai/v1/webhooks/<webhook-id>/test \
  -H "X-Internal-Key: bbas_..."

Your endpoint receives a real signed POST withX-Bizbasics-Event: webhook.test and a body like:

{
  "test": true,
  "endpoint_id": "...",
  "product_id":  "...",
  "triggered_at": "2026-05-31T18:42:00+00:00",
  "message": "If you're seeing this, your endpoint is reachable and the signature verified."
}

Retries: up to 3 attempts with 5s / 10s / 15s backoff (a delivery counts as success on HTTP < 300). After 10 consecutive failures across any events, the endpoint is auto-disabled and you'll need to re-enable it.

Verifying the signature

# Node.js example
const crypto = require("crypto");

function verify(req, secret) {
  const sig = req.headers["x-bizbasics-signature"];
  if (!sig?.startsWith("sha256=")) return false;
  const expected = "sha256=" +
    crypto.createHmac("sha256", secret).update(req.rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Event types

• org.created, org.deactivated, org.deleted
• org.sandbox.reset — a sandbox tenant was wiped; purge your copy of its data
• member.added, member.removed, member.role_changed
• subscription.created, subscription.cancelled
• entitlement.granted, entitlement.revoked
• webhook.test (only sent via the test endpoint)

The delivered body is { "event_type": "...", "payload": { ... } }; the per-attempt delivery id is in the X-Bizbasics-Delivery header.

Status

Self-service registration + a dashboard listing your registered endpoints + per-endpoint delivery history are tracked as follow-ups.