Payment failed

Fires when Stripe fails to collect an invoice, for example because the card was declined. Stripe retries on its own schedule, and each failed attempt is a payment of its own and fires again. data.payment is the failed payment: status: failed, the amount that was due, and balance: 0, plus failureReason, why Stripe couldn't collect it.

Headers

X-Webhook-Signature
Type: string
required

t=<timestamp>,s=<signature>. t is when the delivery was signed, in Unix milliseconds; each attempt is signed afresh, so a retry has a new t. s is the Base64 (standard alphabet, padded) HMAC-SHA256 of the string <t>.<raw request body>, keyed with your signing secret: the whole whsec_… string as UTF-8. To verify, recompute it over the raw body exactly as received and compare in constant time, then reject a t too far from now (5 minutes is a good limit) so an old delivery can't be replayed. s can end in =, so split each part on its first = only.

Body

required

application/json

Every delivery's body.

- data
  Type:
  required
  
  The event's payload, under the key the event names.
  
  Properties: 1
- event
  enum
  const:
  billing-payment-failed
  required
  
  A billing event you can receive. billing-invoice-paid, billing-invoice-posted, billing-invoice-refunded, billing-checkout-created, billing-checkout-completed, billing-checkout-expired, billing-payment-succeeded, billing-payment-failed, billing-credits-depleted, billing-overage-incurred and billing-credit-cap-reached; each is described in the Webhooks section.
  
  values
  billing-invoice-paid
  billing-invoice-posted
  billing-invoice-refunded
  billing-checkout-created
  billing-checkout-completed
  billing-checkout-expired
  billing-payment-succeeded
  billing-payment-failed
  billing-credits-depleted
  billing-overage-incurred
  billing-credit-cap-reached
- id
  Type: string
  required
  
  The delivery's ID (whd_…), the same on every retry of it: keep the IDs you've handled and ignore a delivery whose ID you've seen. A test delivery has an ID of its own.
- isTest
  Type: boolean
  required
  
  true for a delivery sent with Send a test delivery, whose data is placeholder; false otherwise.
- timestamp
  Type: stringFormat: date-time
  required
  
  When the event happened, and the delivery was first queued; the same on every retry.

Responses

200

Return any 2xx to acknowledge. Any other status, a redirect (redirects aren't followed), or no answer within 5 seconds is a failed attempt, recorded in the webhook's lastStatus. A failed delivery is retried 1 minute, 5 minutes, 30 minutes, 2 hours and then 12 hours after each failed attempt in turn (retries are sent by a sweep that runs every minute, so each can be up to a minute later), and dropped after the sixth failed attempt. A retry carries the same id and timestamp and goes to the webhook's current URL; a delivery whose webhook has since been switched off is dropped. Because of retries, an event can arrive more than once or after a later one: use id to ignore repeats. The response body is ignored.

postbilling-payment-failed

{
  "id": "whd_Gm5Rd8Hq2Wz6Kc4V",
  "event": "billing-payment-failed",
  "timestamp": "2026-11-06T03:12:44.640Z",
  "isTest": false,
  "data": {
    "payment": {
      "id": "pay_DXnr4kTDSNNiGg4v",
      "number": 47,
      "customerId": "cus_Z8rT3nW6yP0aJc5E",
      "invoiceId": "inv_dmdae6RsVMaW7T5I",
      "orderId": "ord_2Lp9Xc4Vb7Nm1Qz6",
      "amount": 10692,
      "allocatedAmount": 0,
      "balance": 0,
      "currency": "USD",
      "paymentDate": "2026-11-06T03:12:44.611Z",
      "paymentType": "creditCard",
      "status": "failed",
      "metadata": null,
      "createdAt": "2026-11-06T03:12:44.611Z",
      "updatedAt": "2026-11-06T03:12:44.611Z",
      "failureReason": "insufficient_funds"
    }
  }
}

No Body

Return any 2xx to acknowledge. Any other status, a redirect (redirects aren't followed), or no answer within 5 seconds is a failed attempt, recorded in the webhook's lastStatus. A failed delivery is retried 1 minute, 5 minutes, 30 minutes, 2 hours and then 12 hours after each failed attempt in turn (retries are sent by a sweep that runs every minute, so each can be up to a minute later), and dropped after the sixth failed attempt. A retry carries the same id and timestamp and goes to the webhook's current URL; a delivery whose webhook has since been switched off is dropped. Because of retries, an event can arrive more than once or after a later one: use id to ignore repeats. The response body is ignored.

Payment succeeded

Credits depleted