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;429withRetry-Afterbeyond that). - Errors are JSON problem documents with a stable
code. POST requests accept anIdempotency-Keyheader, 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.
| Area | Endpoints |
|---|---|
| Key | GET /me |
| Products | GET/POST /products (create with plans), GET/PATCH /products/{id|slug}, POST /products/{id}/plans, PATCH /products/{id}/plans/{plan} (archive/activate) |
| Checkouts | POST /checkouts → {url, checkout_id, checkout}; GET /checkouts/{id} |
| Transactions | GET /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) |
| Access | GET /paid?email=|customer_id=|code=&product= → {paid, level, valid_until, subscription_status, last_transaction} |
| Customers | GET /customers (email, created from/to); GET /customers/{id} (with access per product) |
| Subscriptions | GET /subscriptions, GET /subscriptions/{id}, POST /subscriptions/{id}/cancel ({"at_period_end": true} default) /pause /resume |
| Payment links | GET/POST /payment-links, GET /payment-links/{id}, POST /payment-links/{id}/revoke |
| Webhooks | GET/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 |
| Analytics | GET /analytics/summary?range=7d|30d|90d|12m|mtd|ytd|custom&from&to&product |
| Licensing | GET /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).
| Event | When |
|---|---|
payment.paid | A purchase, a subscription's first or renewal charge, or an offline payment. |
payment.failed | A payment attempt failed. |
payment.refunded | A full or partial refund was confirmed. |
subscription.started | A subscription began (trialing or active), including no-card trials. |
subscription.renewed | A renewal charge succeeded. It arrives together with payment.paid. |
subscription.past_due | A renewal charge failed. |
subscription.canceled | The subscription ended. |
subscription.paused | The subscription was paused. |
subscription.resumed | A paused subscription resumed. |
subscription.plan_changed | A requested plan change took effect, at the renewal. |
dispute.opened | A dispute, inquiry or fraud warning opened. |
dispute.closed | A dispute was won, lost or closed. |
ping | Test 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-Idto 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]]indata/config.phplifts 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).