A recurring charge failed

webhook

subscription.payment.failed

Sent when a recurring charge fails to settle. data is the Payment
record; see data.failure.reason. resourceId and
data.subscriptionId are the parent subscription. A failed charge is
followed by subscription.past_due once the subscription enters the
grace period.

Payload

A subscription.payment.failed event.

uuid

required

Unique id of this delivery (UUIDv7), mirrored in the webhook-id
header and covered by the signature. Retries of the same event
repeat this id, so use it to dedupe. A replayed event gets a new
id — see sequence.

type

const

enum

required

Identifies the event — one of the types listed under Webhooks.
Also sent as the webhook-type header.

Allowed:

timestamp

date-time

required

When the event occurred (ISO-8601 UTC, sub-second precision). This
is the event's own time and is preserved on retries and replays —
it is not the webhook-timestamp header, which is stamped per
attempt and is what the signature covers.

sequence

int64

required

≥ 1

Monotonically increasing counter, per resourceId, starting at 1.
Payment events share their parent subscription's counter. Apply an
event only if its sequence is higher than the last one you
applied for that resourceId; that discards both stale
redeliveries and replays of old events. Also sent as the
webhook-sequence header. Not guaranteed gap-free.

resourceType

const

enum

required

The kind of resource this event is about. Always subscription.

Allowed:

resourceId

uuid

required

The subscription this event concerns — always the subscription id,
even for payment events, which route to their parent subscription.

data

object

required

A single recurring-billing charge. One record per attempted cycle;
starts as PENDING and settles to SUCCEEDED or FAILED.

Response

2XX

Return any 2xx status to acknowledge receipt. Any other response
(or a timeout) is treated as a delivery failure and retried.