Billing API
Events and webhooks
Get a signed HTTPS request the moment a payment, subscription, customer or invoice changes.
How webhooks work
Add an endpoint under Developers → Keys & webhooks: a public https:// URL and the events it wants. When one happens, Cycle sends it a POST with the event as JSON. Answer with any 2xx status within 10 seconds.
Endpoints belong to one business and one mode: test endpoints get test events, live endpoints live events. Use Send test event to try yours.
Request
POST /webhooks/cycle HTTP/1.1
Content-Type: application/json
User-Agent: Cycle-Webhooks/1.0
Cycle-Event-Id: evt_2d61f0
Cycle-Event-Type: payment.succeeded
Cycle-Delivery-Id: whd_6a0b1e
Cycle-Signature: t=1794483139,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
{
"id": "evt_2d61f0",
"object": "event",
"type": "payment.succeeded",
"livemode": false,
"created_at": "2026-11-12T09:31:02+00:00",
"data": {
"object": {
"id": "pay_b53be1",
"object": "payment",
"amount": 1200000,
"amount_refunded": 0,
"currency": "AMD",
"status": "succeeded",
"type": "subscription",
"description": "Yoga membership",
"customer": "cus_8f2a1c",
"subscription": "sub_51e0d2",
"invoice": "in_9a7f3c",
"card": {
"brand": "visa",
"last4": "4242"
},
"failure_code": null,
"failure_message": null,
"livemode": false,
"succeeded_at": "2026-11-12T09:31:02+00:00",
"created_at": "2026-11-12T09:31:00+00:00"
}
}
}Event types
| Type | When |
|---|---|
customer.created | A customer was created (dashboard, checkout or API). |
customer.updated | A customer's details or default card changed. |
customer.deleted | A customer was deleted. |
subscription.created | A subscription was created. |
subscription.updated | A subscription changed: renewed, paused, resumed, set to cancel, plan or discount changed. |
subscription.past_due | A renewal failed and the subscription is waiting for a retry. |
subscription.recovered | A past-due subscription was paid and is active again. |
subscription.canceled | A subscription ended. |
checkout.session.completed | A customer finished a checkout: paid, or saved a card for a trial. Carries your client_reference_id. |
payment.succeeded | A card payment succeeded. |
payment.failed | A card payment was declined. |
payment.needs_review | The bank couldn't confirm a charge for a long time: check it in your bank's portal and record what happened. |
refund.succeeded | A payment was refunded, in full or in part. |
invoice.finalized | An invoice got its number and can be paid. |
invoice.paid | An invoice was paid. |
invoice.voided | An invoice was voided. |
invoice.uncollectible | An invoice was closed after the last failed retry. |
dispute.opened | A customer disputed a payment with their bank (a chargeback). |
dispute.closed | The bank decided a dispute: won or lost. |
data.object is the object as the Billing API returns it at the time of the event.
Verify the signature
Every request has Cycle-Signature: t=<unix time>,v1=<signature>. The signature is the hex HMAC-SHA256 of <t>.<raw request body> with your endpoint's signing secret (whsec_…). Recompute it, compare in constant time, and reject timestamps older than 300 seconds to stop replays.
$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_CYCLE_SIGNATURE'] ?? ''), $parts);
$expected = hash_hmac('sha256', $parts['t'].'.'.$body, getenv('CYCLE_WEBHOOK_SECRET'));
if (! hash_equals($expected, $parts['v1'] ?? '') || abs(time() - (int) $parts['t']) > 300) {
http_response_code(400);
exit;
}
$event = json_decode($body, true);Retries and failures
If your endpoint doesn't answer with a 2xx within 10 seconds, Cycle tries again: immediately, 10 seconds, 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours after the previous try (8 attempts in all, about a day). Redirects aren't followed.
After 20 failed attempts in a row the endpoint is disabled and nothing more is sent until you turn it back on. Every attempt, with the status and the start of your response, is under Developers → Deliveries, where you can resend any delivery.
Best practices
- Answer fast. Return
200right away and do slow work in a background job. - Expect duplicates. A delivery can arrive more than once. Use the event
idto process each event once. - Don't rely on order. Events can arrive out of order; read the current object from the API when order matters.
- Catch up. If your server was down, list missed events with
GET /api/v1/events.