Skip to content
On this page

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

TypeWhen
customer.createdA customer was created (dashboard, checkout or API).
customer.updatedA customer's details or default card changed.
customer.deletedA customer was deleted.
subscription.createdA subscription was created.
subscription.updatedA subscription changed: renewed, paused, resumed, set to cancel, plan or discount changed.
subscription.past_dueA renewal failed and the subscription is waiting for a retry.
subscription.recoveredA past-due subscription was paid and is active again.
subscription.canceledA subscription ended.
checkout.session.completedA customer finished a checkout: paid, or saved a card for a trial. Carries your client_reference_id.
payment.succeededA card payment succeeded.
payment.failedA card payment was declined.
payment.needs_reviewThe bank couldn't confirm a charge for a long time: check it in your bank's portal and record what happened.
refund.succeededA payment was refunded, in full or in part.
invoice.finalizedAn invoice got its number and can be paid.
invoice.paidAn invoice was paid.
invoice.voidedAn invoice was voided.
invoice.uncollectibleAn invoice was closed after the last failed retry.
dispute.openedA customer disputed a payment with their bank (a chargeback).
dispute.closedThe 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);
The secret is shown once, when you add the endpoint or roll the secret. Rolling replaces it immediately.

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 200 right away and do slow work in a background job.
  • Expect duplicates. A delivery can arrive more than once. Use the event id to 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.