---
title: "Webhook: billing.top_off_failed"
method: POST
path: "billing.top_off_failed"
tags: ["Webhooks"]
---

# Webhook: billing.top_off_failed

`POST billing.top_off_failed` (webhook)

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

- `X-Hedra-Webhook-Id` string, required
- `X-Hedra-Webhook-Timestamp` string, required
- `X-Hedra-Webhook-Event` 'billing.top_off_failed', required
- `X-Hedra-Webhook-Attempt` integer, required
- `X-Hedra-Webhook-Redelivery` 'true' | 'false', required
- `X-Hedra-Webhook-Signature` string, required

## Payload

- TopOffFailedEvent: 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.
  - `id` string, 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_at` string, date-time, required: When the top-up was declined.
  - `reason` 'payment_method_declined', required: Why an automatic top-up did not add funds.
  - `amount_attempted` number, required: The amount the top-up tried to add.
  - `balance` number, required: The API wallet's balance when this event was sent.
  - `currency` string, required: ISO-4217 currency code for every amount in this event.

## Acknowledgement `2XX`

Acknowledged; any `2xx` stops the retry ladder. Other responses are retried per the Webhooks tag.

---

[API](https://skmtc.dev/hedra-labs/apis/hedra-api.md) - [All operations](https://skmtc.dev/hedra-labs/apis/hedra-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hedra-labs/apis/hedra-api/revisions/6ef35a11cefe?raw)