Utopia PaymentsDocs
Webhook events

subscription.renewed

A renewal was paid and a new billing period began. Sent to your endpoint as a signed POST. Answer with any 2xx within 10 seconds; a delivery that fails is retried after 5 seconds, 5 minutes, 30 minutes, and 2, 5, 10 and 10 hours — eight attempts in all, spanning a little more than a day. Verify the signature before trusting the body.

A renewal was paid and a new billing period began.

Sent to your endpoint as a signed POST. Answer with any 2xx within 10 seconds; a delivery that fails is retried after 5 seconds, 5 minutes, 30 minutes, and 2, 5, 10 and 10 hours — eight attempts in all, spanning a little more than a day. Verify the signature before trusting the body.

Header Parameters

webhook-id*string

Unique per event; use it to ignore duplicates.

Match^evt_[0-9a-f]{32}$
webhook-timestamp*string

Unix seconds. Reject deliveries older than a few minutes.

webhook-signature*string

v1, + base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded part of your whsec_ secret.

Request Body

application/json

The event. Read the raw bytes before parsing them: the signature covers exactly what was sent.

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

Example Requests

POST/subscription.renewed

subscription.on_hold Webhook

A renewal failed. When Utopia charges the renewals, it retries on the schedule in `next_retry_at` and emails the customer a payment link; when the card processor charges them, it retries on its own schedule and `next_retry_at` stays null. Sent to your endpoint as a signed POST. Answer with any 2xx within 10 seconds; a delivery that fails is retried after 5 seconds, 5 minutes, 30 minutes, and 2, 5, 10 and 10 hours — eight attempts in all, spanning a little more than a day. Verify the signature before trusting the body.