Webhook: billingtop off failed
POSTed to the default webhook URL when Stripe declines the payment method for an automatic top-up of the API wallet. After a decline, Hedra holds further automatic top-ups until the hold expires, the payment method changes or a top-up is paid, and sends no event for a decline while a hold is in place. Retried on the same schedule as a job delivery, but not listed by GET /webhooks/deliveries and cannot be redelivered. Dedupe on X-Hedra-Webhook-Id and verify X-Hedra-Webhook-Signature before acting.
Headers
Deduplication id: the event's own id (evt_<uuid>), byte-identical across every retry. Signed.
Unix epoch seconds the delivery was signed at; reject it when more than 5 minutes old. Signed.
The event this delivery announces. Signed.
"billing.top_off_failed"1-based attempt number within the current delivery cycle. Informational and outside the signature; do not branch on it.
x >= 1true when an operator asked for this event to be sent again — process it even if its id was already recorded. Signed.
true, false Hex-encoded ed25519 signature over the canonical string documented on the Webhooks tag; verify against the key from GET /webhooks/public-key before acting on the request.
Body
Body of a billing.top_off_failed webhook.
Hedra sends this event when Stripe declines the payment method for an automatic top-up of the API wallet. After a decline, Hedra holds further automatic top-ups until the hold expires, the payment method changes or a top-up is paid, and sends no event for a decline while a hold is in place.
The event's id, the same value as X-Hedra-Webhook-Id.
Always billing.top_off_failed.
billing.top_off_failed When the top-up was declined.
Why an automatic top-up did not add funds.
payment_method_declined The amount the top-up tried to add.
The API wallet's balance when this event was sent.
ISO-4217 currency code for every amount in this event.
Response
Acknowledged; any 2xx stops the retry ladder. Other responses are retried per the Webhooks tag.