Guides

Webhook events

Clearway delivers merchant webhook events to endpoints you configure in the dashboard (Developer → Webhooks). Registration and secret rotation are dashboard-only — not available via API keys.

Configure endpoints at https://app-dev.clearway.to/developer/webhooks/endpoints.

Event types

Event type	Label	Typical trigger
`payment.succeeded`	Payment succeeded	Payment intent succeeded or checkout completed
`payment.failed`	Payment failed	Payment intent failed
`subscription.created`	Subscription created	New payer subscription
`subscription.updated`	Subscription updated	Plan or status change
`subscription.cancelled`	Subscription cancelled	Subscription ended
`billing.dunning`	Billing dunning	Invoice payment failed (grace period)

Envelope shape

Each delivery is a JSON object:


Code
{
  "id": "delivery_uuid",
  "type": "payment.succeeded",
  "created": 1710000000,
  "livemode": false,
  "test": true,
  "api_version": "2026-06-08",
  "data": {
    "object": { }
  }
}

type — one of the event types above
data.object — event-specific payload (payment, subscription, or dunning fields)
test / livemode — sandbox vs production context

Use the dashboard Send test event action to preview payloads for each type.

Verification

Verify x-clearway-signature and x-clearway-timestamp before trusting the body. See Webhooks.

Platform vs merchant webhooks

Platform billing webhooks (your Clearway service plan) are separate from merchant payment event webhooks documented here.

Next steps

Webhooks — signature verification
Subscriptions — API operations alongside events
Errors — delivery failure handling

Last modified on July 22, 2026

Webhook verification Orders and revenue

Event types

Event type

Label

Typical trigger

payment.succeeded

Payment succeeded

Payment intent succeeded or checkout completed

payment.failed

Payment failed

Payment intent failed

subscription.created

Subscription created

New payer subscription

subscription.updated

Subscription updated

Plan or status change

subscription.cancelled

Subscription cancelled

Subscription ended

billing.dunning

Billing dunning

Invoice payment failed (grace period)

Envelope shape

Each delivery is a JSON object:

Code

{
  "id": "delivery_uuid",
  "type": "payment.succeeded",
  "created": 1710000000,
  "livemode": false,
  "test": true,
  "api_version": "2026-06-08",
  "data": {
    "object": { }
  }
}

type — one of the event types above

data.object — event-specific payload (payment, subscription, or dunning fields)

test / livemode — sandbox vs production context

Use the dashboard Send test event action to preview payloads for each type.