Webhook

Webhook

Last reviewed: 16 November 2026 · Status: Partial. Read Limits today before you build on webhooks.

A webhook is a URL in your system that BillHive calls when something happens, such as a subscription being cancelled. Use webhooks to grant or remove access in your product, sync your CRM, or alert your team, without polling the API.

Setting up a webhook

The add webhook form with name, URL and event list

Adding a webhook.

  1. Go to Settings > Webhooks and add a webhook.
  2. Enter a Webhook Name and the Webhook URL (HTTPS, reachable from the internet).
  3. Choose the Content Type (application/json or application/x-www-form-urlencoded). Deliveries are currently always sent as JSON, whichever you pick.
  4. Under Select Events, tick the events you want.
  5. Save. The list shows each webhook’s Url and Status.

Events

You can select any of these events. The Data column says whether the event carries data today.

Subscription events

EventSent whenData
Subscription ActivatedA paid subscription startsSubscription
Trial SubscriptionA trial starts or is activatedSubscription
Subscription RenewedA new term startsSubscription
Subscription ChangedPlan upgraded, downgraded or changed; frequency changed; add-ons added or updated; trial extended; subscription reactivated; scheduled change removed; a change mandate is requiredSubscription
Subscription PausedThe subscription pausesSubscription
Subscription ResumedThe subscription resumesSubscription
Subscription CancelledThe subscription is cancelledSubscription
Subscription ExpiredThe term ends without renewalSubscription
Subscription CreatedA future-dated subscription is createdEmpty
Subscription Scheduled ChangeA plan, frequency or add-on change is scheduledEmpty
Subscription Scheduled CancellationA cancellation is scheduledEmpty
Subscription Expiring SoonBefore the term ends, when not renewingEmpty
Subscription Trial Ending SoonBefore a trial endsEmpty
Post CancellationSome days after a cancellationEmpty

Invoice, payment and credit events

EventSent whenData
Invoice Created, Invoice Paid, Invoice Due Soon, Invoice OverdueInvoice milestonesEmpty
Payment Successful, Payment Failed, Payment Retry Attempt, Payment Final FailurePayment results and dunning retriesEmpty
Refund Issued, Credit Note IssuedMoney returned or creditedEmpty
Payment Method Expiring, Payment Method Expired, Payment Method Updated, Payment Method MissingPayment method changesEmpty
Payment Request Created, Auto Debit ReminderA payment request or upcoming auto-debitEmpty

Dunning reminders (Payment Reminder, Urgent Notice and so on) are emails only; they have no webhook event.

Request format

BillHive sends an HTTP POST with Content-Type: application/json. For subscription events the body is:

{
  "event": "Subscription Cancelled",
  "data": {
    "id": "6f1c2a9e-...",
    "accountId": "b7d4...",
    "status": "Cancelled",
    "...": "the other fields of the subscription"
  }
}

The data object is the subscription as stored at the time of the event, with the same fields as GET /subscriptions/{id}. Events marked Empty above send {}.

Responding

Return any 2xx status quickly, then do the work in the background. BillHive records the delivery as Delivered for a 2xx response and Failed otherwise, with the response status, for support to look into.

Limits today

LimitWhat it means for you
Only subscription events carry dataFor invoices and payments, call the API (e.g. GET /invoices) when you need details, or poll on a schedule
No signature headerYou can’t prove a request came from BillHive. Use a hard-to-guess URL path, accept HTTPS only, and re-read the subscription with GET /subscriptions/{id} before acting on it
One attempt, no automatic retryIf your endpoint is down, the event is lost. Reconcile periodically against the API
No event IDDe-duplicate on event + data.id + data.status

These are the current behaviour, not a design promise. Check the Feature Inventory for updates.

Example: grant and revoke access

See Receive webhooks.