COconfirmo
Webhooks

A recurring charge 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.

postWebhooksubscription.payment.failed

Payload

idstring 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'subscription.payment.failed' required

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

timestampstring 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.

sequenceinteger required

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'subscription' required

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

resourceIdstring uuid required

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

Example payload

{
  "id": "01981e37-9b0c-70d5-8a76-c4e9f0128b3a",
  "type": "subscription.payment.failed",
  "timestamp": "2026-07-29T08:00:07.905412338Z",
  "sequence": 4,
  "resourceType": "subscription",
  "resourceId": "019807c2-6f2a-7b41-9c58-2f9c1a4b8d21",
  "data": {
    "id": "01981e37-9a55-7ee1-b03c-48f7d2610ba9",
    "subscriptionId": "019807c2-6f2a-7b41-9c58-2f9c1a4b8d21",
    "billedAmount": {
      "amount": "29.00",
      "asset": "USD"
    },
    "paidAmount": {
      "amount": "0.00",
      "asset": "USDC"
    },
    "status": "FAILED",
    "failure": {
      "reason": "INSUFFICIENT_BALANCE"
    },
    "cycleNumber": 3,
    "createdAt": 1785312000
  }
}

Response

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

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.