billingHelp

API keys and outbound webhooks

Creating API keys, calling the REST API, and receiving signed webhook events from your workspace.

Settings → API & webhooks is for owners and admins with access to every product. The complete reference, generated from the routes and with a "try it" console, is at /api/docs.

API keys#

  • Read keys can list and read. Read and write keys can also create checkouts, refund, record offline payments and manage webhooks.
  • A key can be limited to some products, to IP addresses (one address or CIDR per line) and to an expiry date.
  • The key is shown once, when you create it. Store it in your server's secret store; only a fingerprint is kept here.
  • Requests send Authorization: Bearer bk_…. Each key may make 600 requests per minute (X-RateLimit-* headers; 429 with Retry-After beyond that).
  • Errors are JSON problem documents with a stable code. POST requests accept an Idempotency-Key header, so a retried request never charges or refunds twice.
  • Renaming a key, changing its products or addresses, and revoking it are all recorded in the audit log.
AreaEndpoints
KeyGET /me
ProductsGET/POST /products (create with plans), GET/PATCH /products/{id|slug}, POST /products/{id}/plans, PATCH /products/{id}/plans/{plan} (archive/activate)
CheckoutsPOST /checkouts → {url, checkout_id, checkout}; GET /checkouts/{id}
TransactionsGET /transactions (status, kind, provider, product, customer, subscription, email, created/paid from/to); GET /transactions/{id} (with refunds); GET /transactions/by-code/{code}; POST /transactions/{id}/refund (full when amount is left out); POST /transactions/manual (offline payment: grants access, issues a license, sends the receipt)
AccessGET /paid?email=|customer_id=|code=&product= → {paid, level, valid_until, subscription_status, last_transaction}
CustomersGET /customers (email, created from/to); GET /customers/{id} (with access per product)
SubscriptionsGET /subscriptions, GET /subscriptions/{id}, POST /subscriptions/{id}/cancel ({"at_period_end": true} default) /pause /resume
Payment linksGET/POST /payment-links, GET /payment-links/{id}, POST /payment-links/{id}/revoke
WebhooksGET/POST /webhooks, GET/PATCH/DELETE /webhooks/{id}, POST /webhooks/{id}/test, POST /webhooks/{id}/rotate-secret, GET /webhooks/{id}/deliveries, POST /webhooks/{id}/deliveries/{d}/redeliver
AnalyticsGET /analytics/summary?range=7d|30d|90d|12m|mtd|ytd|custom&from&to&product
LicensingGET /licenses, GET /licenses/{id}, POST /licenses/{id}/{suspend|resume|revoke|seats|regenerate|expires}, DELETE /licenses/{id}/instances/{instance}, POST …/instances/{instance}/{block|unblock|remove}, GET/POST /products/{id}/signing-keys, POST /products/{id}/signing-keys/{kid}/{activate|retire}. These are the same handlers as the session-based /admin/api/licenses… (LICENSING.md), and the key's product scope applies.

Checkouts created through the API do not record the caller's IP or country, because the caller is your server, not the buyer. The buyer still pays on the provider's hosted page.

Add endpoints on the settings screen or with POST /webhooks. A workspace can have up to 20. The signing secret (whsec_…) is shown once. Each endpoint subscribes to chosen events or to all events (*, which includes events added later).

EventWhen
payment.paidA purchase, a subscription's first or renewal charge, or an offline payment.
payment.failedA payment attempt failed.
payment.refundedA full or partial refund was confirmed.
subscription.startedA subscription began (trialing or active), including no-card trials.
subscription.renewedA renewal charge succeeded. It arrives together with payment.paid.
subscription.past_dueA renewal charge failed.
subscription.canceledThe subscription ended.
subscription.pausedThe subscription was paused.
subscription.resumedA paused subscription resumed.
subscription.plan_changedA requested plan change took effect, at the renewal.
dispute.openedA dispute, inquiry or fraud warning opened.
dispute.closedA dispute was won, lost or closed.
pingTest sends only.

Request

POST <your url>
Content-Type: application/json
Billing-Event: payment.paid
Billing-Event-Id: evt_01J…
Billing-Delivery: 01J…
Billing-Signature: t=1793000000,v1=5f0c…

{"id":"evt_01J…","object":"event","type":"payment.paid","api_version":"v1","created":1793000000,"tenant":"acme",
 "data":{"object":{ …the transaction, subscription or dispute, as the API returns it… }}}

Checking a delivery. v1 = hex(HMAC-SHA256(secret, t + "." + raw body)). Compare in constant time, and reject a t more than 5 minutes away from your clock:

preg_match('/t=(\d+)/', $_SERVER['HTTP_BILLING_SIGNATURE'], $t);
preg_match('/v1=([0-9a-f]{64})/', $_SERVER['HTTP_BILLING_SIGNATURE'], $v);
$raw = file_get_contents('php://input');
$ok = abs(time() - (int) $t[1]) <= 300 && hash_equals(hash_hmac('sha256', $t[1] . '.' . $raw, $secret), $v[1]);

Answering

  • Answer with any 2xx within 10 seconds.
  • Do slow work after answering.
  • Use Billing-Event-Id to ignore repeats: the same event can arrive twice, after a timeout or a redelivery.

Retries. A failed attempt (no answer, a timeout, or a non-2xx status) is retried 1 min, 5 min, 30 min, 2 h and 12 h later. That is 6 attempts over about 15 hours. Then the delivery is marked failed and the workspace owners get one e-mail per endpoint per day. Each delivery's attempts, last status, error and the start of your answer are on the endpoint's page, where you can Send again. Send a test event sends a ping immediately and shows the result.

Security

  • Endpoints must be https:// and public. At creation, and again at every send, the host is resolved, and loopback, private, link-local, carrier-grade NAT and reserved addresses are refused.
  • The connection is pinned to the checked address, so DNS rebinding does not work. Redirects are not followed.
  • For lab setups, 'api' => ['webhooks' => ['allow_private' => true, 'allow_http' => true]] in data/config.php lifts these two rules. These settings are not available on any screen.

Delivery job. The webhooks.deliver job runs every minute. On a cluster it runs on the writable node only. Delivered events are kept 30 days (api.prune).