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.

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

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.