BigMindBigMindBigMind
Partner API
Sign inGet an API key
Partner API
OverviewAuthenticationCustomersPlansQuotesAccount & UsageBackup statusWebhooksError codesChangelog

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.

POST/v1/webhooks

Create 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"] }'
GET/v1/webhooks

List 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.

GET/v1/webhooks/{id}/deliveries

The 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 }
  }
}
POST/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver

Re-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

EventWhen it fires
customer.createdA new customer was successfully provisioned.
customer.updatedPlan, 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.deletedCustomer was deleted — by you (DELETE, with the refund amount) or by the platform (an ended trial past its retention, with deletionReason).
subscription.createdSubscription activated for a customer.
subscription.updatedSubscription plan or period changed.
subscription.cancelledSubscription cancelled (typically alongside customer deletion).
subscription.renewedThe 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_upcomingSent 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.lowYour partner credit balance dropped to $10 or less.
credits.depletedYour partner credit balance hit zero.
customer.suspendedThe 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.reactivatedBack in service — by you (detail.reason partner, status) or by a top-up that cleared a credit suspension (reason top_up).
customer.grace_startedThe renewal could not be charged; the customer stays in service until detail.graceUntil (graceDays, requiredCredits, balance, fundedBy).
customer.grace_endedThe grace period is over: detail.outcome paid (the renewal was charged, chargedWholesale) or suspended.
customer.trial_convertedThe free trial became a paid plan: detail.wholesaleCharged, fundedBy (self or distributor), periodEnd.
customer.trial_endedThe free trial ended without converting; the account is kept until detail.deletesOn.
customer.plan_change_scheduledA 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_appliedThe scheduled change took effect at the renewal: detail.fromPlanId, toPlanId, changed[], billingCycle, users, extraUsers. subscription.updated fires too.
customer.plan_change_droppedThe renewal could not make the scheduled change: detail.reason (CAPACITY_EXCEEDED, PLAN_GONE …), pendingChange, problems.
customer.storage_alertThe 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.failedA 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.recoveredThe device's next successful backup after a failure streak; consecutiveFailures says how many it took.
partner.price_change_noticeYour 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.testNot 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.attachedYou attached a medical report to a DICOM study via the Partner API. Payload includes studyInstanceUid + report metadata.
dicom.report.detachedYou 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 key
  • X-Webhook-Event — event name, e.g. customer.created
  • X-Webhook-Timestamp — ISO 8601 delivery time
  • X-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 timestamp if ordering matters.