Signed delivery events

Set an HTTPS receiver in Profile, generate a callback secret and select the required account notifications. Completion events for native async work use the configured receiver. Deliveries come from a durable retry queue rather than the browser tab that submitted a request.

Request envelope

POST /b2b/events HTTP/1.1
Content-Type: application/json
X-Callback-Event-ID: EVENT_PUBLIC_ID
X-Callback-Signature: t=1788950400,v1=HEX_DIGEST

{"event_id":"EVENT_PUBLIC_ID","event":"account.balance_low","occurred_at":"2026-09-09T12:00:00Z","data":{"balance":"9.5000000000","threshold":"20.0000000000","currency":"USD"}}

The neutral X-Callback-* aliases are emitted by this release. The signature is HMAC-SHA256 over <timestamp>.<raw_body> with the secret from Profile. Verify the raw bytes before parsing or reserializing JSON; compare digests in constant time and enforce a replay window appropriate to your receiver.

Response

HTTP/1.1 200 OK
Content-Length: 0

Any 2xx acknowledges delivery. Persist and deduplicate by event_id before acknowledging, then perform longer work in your own application queue. A retry has the same event ID but may have a new signature timestamp. Ignore additional payload fields your application does not yet use.

Available event data

key.spend_limit_threshold_reached identifies the key and includes exact usage, spend_limit, threshold percentage and currency. group.spend_limit_threshold_reached provides the corresponding project fields. account.balance_low contains the current balance and configured threshold. request.completed contains the request ID, terminal status, nullable upstream status and retained response or error. Keep monetary strings exact.

Threshold conditions are checked approximately once per minute and rearm after the condition clears. They are operational notifications, not instantaneous budget reservations.

Delivery constraints

The receiver must be publicly reachable; private, loopback and other disallowed address ranges are rejected, including redirects to them. TLS verification stays enabled. Each attempt has a 15-second limit. The total is six attempts, with retry delays of 5 seconds, 30 seconds, 2 minutes, 10 minutes and 1 hour after successive failures. Non-2xx, transport errors and timeouts fail an attempt. After the sixth failure, delivery stops.

Do not publish the callback secret or full Authorization headers in diagnostics. For missed events, inspect delivery status and reconcile through the relevant Partner read endpoints.