Webhooks and budgets
Instead of polling, let the platform tell you: an invoice was issued, paid or became overdue, the balance
dropped below your threshold, a project was created, suspended, resumed or deleted, a project reached a
share of its budget. Events go to an HTTPS address of yours as signed POST requests. A budget per
project sends those alerts; it does not limit or stop anything.
Webhooks are managed with an account key that has billing access (see Billing data), changes need read and write access.
1. Subscribe
curl -X POST -H "Authorization: Bearer $FBX_ACCOUNT_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" https://api.fiberax.com/v1/webhooks \
-d '{"url": "https://hooks.example.com/fiberax", "events": ["invoice.created", "invoice.paid", "invoice.overdue", "balance.low"], "balance_threshold": "50.00"}'
The answer carries secret (whsec_...) - only this once; store it now. An account holds up to
10 subscriptions, one per URL.
- The URL must be
https://on port 443 with a host name, not an IP address. Every address the name resolves to must be public: private networks, loopback, link-local and our own addresses are refused with422 invalid_webhook_url, and the reason is named. The check repeats before every delivery, so a name that later points inside a private network gets nothing. - Redirects are not followed: answer the
POSTwhere you subscribed.
2. Verify the signature
Each delivery is a POST with the event as JSON and three headers, per
Standard Webhooks: webhook-id (the event id),
webhook-timestamp (Unix seconds) and webhook-signature: v1, followed by base64 of
HMAC-SHA256 over id.timestamp.body, keyed with the bytes of the base64 after whsec_. Any Standard
Webhooks library verifies it with the secret as it is:
from standardwebhooks import Webhook event = Webhook(secret).verify(request_body, request_headers) # raises if the signature or the time is wrong
- Answer
2xxwithin 5 seconds; do the work after answering. Anything else is a failure. A slow endpoint gets at most two deliveries a minute and waits for the rest - other accounts are not held up by it. - Deliveries can repeat and arrive out of order: deduplicate by
webhook-id, and read the current state through the API if order matters. The body is thin - ids and a few figures, never names or e-mail addresses. - A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, 2, 5, 10 and 10 hours, then given up
(
abandoned). If every delivery fails for 72 hours, the subscription is disabled and the account owner gets an e-mail naming the subscription and the host of its URL; set itsstatustoactiveto resume. POST /v1/webhooks/{id}/actions/rotate-secretissues a new secret; for 24 hours deliveries carry a signature with the old one too, so you can switch over without losing events.
3. See what happened
curl -H "Authorization: Bearer $FBX_ACCOUNT_KEY" https://api.fiberax.com/v1/webhooks/7/deliveries curl -H "Authorization: Bearer $FBX_ACCOUNT_KEY" "https://api.fiberax.com/v1/events?type=invoice.paid"
The delivery log shows the result of each delivery: the status your endpoint answered and the first 256 bytes of
its body. POST .../deliveries/{id}/actions/retry sends one again. GET /v1/events lists the events of
the last 30 days whether they were delivered or not - use it to catch up after downtime.
POST /v1/webhooks/{id}/actions/test sends a webhook.test event within a minute.
Events are found by the platform within about a minute of the change (budget events up to an hour later, after usage is recorded), so a webhook is not a real-time signal. Treat a type you do not know as legitimate and skip it.
4. A budget per project
curl -X PUT -H "Authorization: Bearer $FBX_ACCOUNT_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" https://api.fiberax.com/v1/projects/1313/budget \
-d '{"amount": "250.00", "thresholds": [50, 80, 100]}'
About hourly, after usage is recorded, the platform compares what the project charged in its billing period with
the budget. Each threshold reached sends budget.threshold_reached once per period, the budget reached sends
budget.exceeded - to subscriptions that include those types. Another amount, or a new currency of the account, is a new budget:
raise it with PUT and reach it again, and both are sent again for the new amount; writing the same amount
again does not repeat them. period_start in these events is UTC with Z, the same value the budget read returns.
- A budget only informs: nothing is refused and nothing is stopped when it is reached - servers keep running and charging, and new resources can be created as before. To hold spending, act on the events in your own automation.
- Usage is recorded an hour or two late, so an event comes after the amount is actually reached.
- If the currency of the account changes, the budget is not evaluated until you write it again with
PUT. - A budget belongs to the account that set it: if the project is transferred to another account, the budget stops applying and is removed.
- Any key of the project reads the budget with
GET /v1/project/budget.