Webhooks
Subscribe to real-time events so your systems can react to customer and billing changes without polling.
Setup
Configure webhooks in Settings → Webhooks, or by API (below). Each webhook has a URL, a list of event subscriptions, and a signing secret shown once when it is created. Up to 10 endpoints (e.g., one for billing, one for support tooling). Only the events listed below can be subscribed to; an unknown event name is refused when the webhook is saved. The endpoint must be a public HTTPS (or HTTP) address: private, link-local and cloud-metadata addresses are refused, and redirects are not followed.
Manage endpoints by API
Everything the Settings page does is on the API, so an integration can register its own endpoint during setup. Up to 10 endpoints per partner. The signing secret is returned once — on create and on rotate — and shown as a prefix afterwards.
/v1/webhooksCreate an endpoint: { name, url, events[], active? }. The url may be at most 191 characters (a longer one is 400 VALIDATION_FAILED). The answer carries secret — this is the only time. 400 UNKNOWN_WEBHOOK_EVENT (details.allowed lists the events), 400 INVALID_WEBHOOK_URL, 400 WEBHOOK_LIMIT_REACHED at 10.
curl -X POST https://eu-bigmind2.genie9.com/api/partner/v1/webhooks \
-H "Authorization: Bearer sk_live_..." -H "Content-Type: application/json" \
-d '{ "name": "Billing sync", "url": "https://hooks.example.com/bigmind", "events": ["customer.created", "subscription.renewed", "credits.low"] }'/v1/webhooksList your endpoints (secretPrefix, counters, last error). GET /v1/webhooks/{id} reads one; PATCH /v1/webhooks/{id} changes name, url, events or active; DELETE removes it with its delivery log; POST /v1/webhooks/{id}/test sends webhook.test now and answers with the outcome and the deliveryId; POST /v1/webhooks/{id}/rotate-secret answers a new secret once — the old one stops signing at once, so update your endpoint first.
/v1/webhooks/{id}/deliveriesThe delivery log, newest first, kept 30 days: ?status=pending|retrying|success|failed, ?event=, ?from= and ?to= (ISO 8601), page / limit (max 200). Each row is one event to this endpoint and shows its LAST attempt: eventId, event, status, statusCode, attempts made / maxAttempts (the first delivery plus the retries: 4 for a normal delivery, 1 for a test or a redelivery), deliveryTimeMs, error, createdAt, deliveredAt, redeliveredFrom. GET …/deliveries/{deliveryId} adds request (the envelope as sent) and response.
{
"success": true,
"data": {
"deliveries": [
{ "id": "whlog_1759…", "eventId": "evt_mgb2k1…", "event": "customer.created", "status": "success", "statusCode": 200,
"attempts": 1, "maxAttempts": 3, "deliveryTimeMs": 212, "error": null,
"createdAt": "2026-10-05T09:01:00.000Z", "deliveredAt": "2026-10-05T09:01:00.212Z", "nextRetryAt": null, "redeliveredFrom": null },
{ "id": "whlog_1758…", "eventId": "evt_mgb1x0…", "event": "subscription.renewed", "status": "failed", "statusCode": 503,
"attempts": 4, "maxAttempts": 4, "deliveryTimeMs": 7410, "error": "HTTP 503: Service Unavailable",
"createdAt": "2026-10-05T00:05:02.000Z", "deliveredAt": null, "nextRetryAt": null, "redeliveredFrom": null }
],
"pagination": { "page": 1, "limit": 50, "total": 2, "pages": 1 }
}
}/v1/webhooks/{id}/deliveries/{deliveryId}/redeliverRe-send a delivery: the stored envelope goes out again as a NEW delivery row with the same event id (X-Webhook-Id), a fresh timestamp and signature, and redeliveredFrom naming the source. One attempt, no retries (like Test); the payload is as it was, not refreshed; the endpoint must be active. Answers 201 with the new row; 429 (Retry-After) when the same event was redelivered to this endpoint less than a minute ago.
Available events
| Event | When it fires |
|---|---|
| customer.created | A new customer was successfully provisioned. |
| customer.updated | Plan, users, add-ons or status changed — by you (PATCH, suspend, reactivate, a scheduled change) or by the platform (grace period started, suspended for credit, reactivated by a top-up, trial converted or ended, a scheduled change applied or dropped at the renewal). The payload carries the status and the plan as they are now. |
| customer.deleted | Customer was deleted — by you (DELETE, with the refund amount) or by the platform (an ended trial past its retention, with deletionReason). |
| subscription.created | Subscription activated for a customer. |
| subscription.updated | Subscription plan or period changed. |
| subscription.cancelled | Subscription cancelled (typically alongside customer deletion). |
| subscription.renewed | The daily renewal charged your credit (or your distributor's) and advanced the customer's period. Payload includes the amount and the new period. |
| customer.renewal_upcoming | Sent 7, 3 and 1 days before a customer's renewal, with the date and the amount that will be deducted. A reminder that could not go out on its day follows on the next run; renewal.daysUntilRenewal always gives the real number of days. renewal.suspended is true for a customer you suspended: it is still renewed and charged. |
| credits.low | Your partner credit balance dropped to $10 or less. |
| credits.depleted | Your partner credit balance hit zero. |
| customer.suspended | The customer was suspended — by you (detail.reason partner) or by the daily run for credit (reason credit, with graceUntil). customer.updated fires too. For a credit suspension, detail.deletesOn is the date its account and data are scheduled to be deleted unless the renewal is paid first. |
| customer.reactivated | Back in service — by you (detail.reason partner, status) or by a top-up that cleared a credit suspension (reason top_up). |
| customer.grace_started | The renewal could not be charged; the customer stays in service until detail.graceUntil (graceDays, requiredCredits, balance, fundedBy). |
| customer.grace_ended | The grace period is over: detail.outcome paid (the renewal was charged, chargedWholesale) or suspended. |
| customer.trial_converted | The free trial became a paid plan: detail.wholesaleCharged, fundedBy (self or distributor), periodEnd. |
| customer.trial_ended | The free trial ended without converting; the account is kept until detail.deletesOn. |
| customer.plan_change_scheduled | A smaller plan, fewer users or a new cycle was recorded for the renewal: detail.pendingChange (planId, billingCycle, seats, extraUsers, planName, retail, effectiveAt). |
| customer.plan_change_applied | The scheduled change took effect at the renewal: detail.fromPlanId, toPlanId, changed[], billingCycle, users, extraUsers. subscription.updated fires too. |
| customer.plan_change_dropped | The renewal could not make the scheduled change: detail.reason (CAPACITY_EXCEEDED, PLAN_GONE …), pendingChange, problems. |
| customer.storage_alert | The account crossed 80 % (detail.level warning) or 100 % (critical) of a storage pool: detail.tier (hot, cold or deep_freeze) names the pool, and percentage, usedBytes and limitBytes are that pool's. At most once a week per pool and level, like the emails. |
| backup.failed | A device's backup failed — the FIRST failure of a streak; later failures in the same streak are counted, not sent. detail.device {id, name}, session {id, status, startedAt, endedAt, filesProcessed, filesSuccess, filesFailed, error}, consecutiveFailures. |
| backup.recovered | The device's next successful backup after a failure streak; consecutiveFailures says how many it took. |
| partner.price_change_notice | Your distributor raised prices on your template, effective in 30 days: detail.distributorName, effectiveAt, changes[] {key, label, from, to}. A partner-level event: data has partnerId and detail, no customer. |
| webhook.test | Not a subscription: sent to the endpoint when you press Test (Settings → Webhooks, or POST /v1/webhooks/{id}/test), whatever its events. Its data is { message, webhook_id, partner_id }; one attempt, logged like any delivery. |
| dicom.report.attached | You attached a medical report to a DICOM study via the Partner API. Payload includes studyInstanceUid + report metadata. |
| dicom.report.detached | You detached a partner-uploaded report. |
Payload format
All webhook payloads use this envelope. id is the event's identity (evt_…): the same on every endpoint, every retry and a redelivery — store it and ignore a second arrival.
{
"id": "evt_mgb2k1f0a3c9d2e8b7a1",
"event": "customer.created",
"timestamp": "2026-05-13T15:42:11.000Z",
"data": {
"customer": {
"id": "pc_42_1715600000000",
"email": "acme@example.com",
"name": "Acme Co",
"organizationId": "org_42_1715600000001",
"partnerId": 42,
"companyName": "Acme Co Ltd",
"phone": "+1-555-0100",
"status": "active",
"planId": "bigmind-standard-monthly",
"planName": "Acme Backup Standard",
"planDisplayName": "BigMind Resilience Standard",
"seats": 10,
"billingCycle": "monthly",
"retailPrice": 100,
"nextBillingDate": "2026-06-13T15:42:11.000Z",
"addOns": { "hotStorageGB": 0, "coldStorageGB": 0, "extraServers": 0 },
"storage": { "hotStorageGB": 5000, "coldStorageGB": 0, "totalServers": 0 },
"accountFocusMode": "generic",
"language": "en",
"createdAt": "2026-05-13T15:42:11.000Z"
}
}
}Lifecycle and operations events: the detail block
The dedicated events carry the same customer object as customer.updated plus detail — the facts of the moment. One sample per family:
{
"id": "evt_mgb3…", "event": "customer.grace_started", "timestamp": "2026-06-13T00:05:02.000Z",
"data": {
"customer": { "id": "pc_42_…", "email": "acme@example.com", "status": "active", "planId": "bigmind-standard-monthly", "...": "..." },
"detail": { "graceUntil": "2026-06-20T00:00:00.000Z", "graceDays": 7, "requiredCredits": 68, "balance": 12.5, "fundedBy": "self" }
}
}Signature verification
Every webhook request includes an X-Webhook-Signature header — an HMAC-SHA256 of the raw JSON body using your webhook's signing secret. Verify it on every request to confirm the payload came from BigMind and hasn't been tampered with.
import crypto from 'node:crypto';
export function verifySignature(rawBody, signatureHeader, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex');
// timing-safe compare
const a = Buffer.from(expected);
const b = Buffer.from(signatureHeader);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Headers
Each delivery includes:
X-Webhook-Id— the event id (evt_…), the same on every endpoint, retry and redelivery; your deduplication keyX-Webhook-Event— event name, e.g.customer.createdX-Webhook-Timestamp— ISO 8601 delivery timeX-Webhook-Attempt— attempt number (1 for the first delivery, 2–4 for the retries)X-Webhook-Signature— HMAC-SHA256 hex
Retries
A delivery that fails (a 5xx answer, a network error, or no answer within 10 seconds) is retried up to 3 times with exponential backoff (1s, 2s, 4s). A 4xx answer is not retried: it says the request itself was rejected. After that the delivery is failed: see it in the delivery log (Settings → Webhooks → Deliveries, or GET /v1/webhooks/{id}/deliveries) and redeliver it once your endpoint is back.
Your endpoint should:
- Return a 2xx response within 10 seconds. Queue any heavy work for async processing.
- Be idempotent — the same event may arrive multiple times during retries.
- Tolerate out-of-order delivery — use
timestampif ordering matters.