Webhooks

Webhooks notify your application when objects change in Rollo. You register an HTTPS endpoint and subscribe to specific event types. Only subscribed events are delivered to that endpoint.

Subscribe in the dashboard

Open Dashboard → Webhooks, enter your endpoint URL, and select the event types your integration handles. You can edit subscriptions later, disable an endpoint temporarily, or roll the signing secret if it is compromised. The signing secret is shown once at creation—store it in your secrets manager.

Prefer the narrowest set of events that meets your needs. Subscribing to every event increases noise and processing cost without improving reliability.

Event types

• checkout_session.completed — Checkout finished successfully
• checkout_session.expired — Session expired unpaid
• payment.succeeded — Charge succeeded
• payment.failed — Charge failed
• payment.refunded — Refund issued
• customer.created — Customer record created
• subscription.created — Subscription created
• subscription.updated — Subscription changed
• subscription.trial_will_end — Trial ending soon
• subscription.canceled — Subscription canceled
• invoice.paid — Subscription invoice paid
• invoice.payment_failed — Invoice payment failed
• dispute.created — Dispute opened
• payout.paid — Payout deposited

Payload & verification

Each delivery includes a JSON body and a Rollo-Signature header. Compute an HMAC-SHA256 over the raw request body with your endpoint secret and compare it to the signature. Reject invalid or replayed requests. Respond with HTTP 2xx quickly; Rollo retries failed deliveries. Design handlers to be idempotent using the event id.

{
  "id": "evt_...",
  "type": "payment.succeeded",
  "created": 1723000000,
  "data": {
    "object": {
      "id": "pay_...",
      "amount": 4900,
      "currency": "usd",
      "checkout_session": "cs_..."
    }
  }
}