HEhedra-labs
Webhooks

Webhook: billing.top_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.

postWebhookbilling.top_off_failed

Headers

X-Hedra-Webhook-Idstring required

Deduplication id: the event's own id (evt_<uuid>), byte-identical across every retry. Signed.

X-Hedra-Webhook-Timestampstring required

Unix epoch seconds the delivery was signed at; reject it when more than 5 minutes old. Signed.

X-Hedra-Webhook-Event'billing.top_off_failed' required

The event this delivery announces. Signed.

X-Hedra-Webhook-Attemptinteger required

1-based attempt number within the current delivery cycle. Informational and outside the signature; do not branch on it.

X-Hedra-Webhook-Redelivery'true' | 'false' required

true when an operator asked for this event to be sent again — process it even if its id was already recorded. Signed.

X-Hedra-Webhook-Signaturestring required

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.

Payload

idstring required

The event's id, the same value as X-Hedra-Webhook-Id.

type'billing.top_off_failed' required

The billing events an outbound webhook announces.

Separate from WebhookEventType, which names the events of the job deliveries GET /webhooks/deliveries lists. GET /webhooks/deliveries does not list these.

created_atstring date-time required

When the top-up was declined.

reason'payment_method_declined' required

Why an automatic top-up did not add funds.

amount_attemptednumber required

The amount the top-up tried to add.

balancenumber required

The API wallet's balance when this event was sent.

currencystring required

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.

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.