payment.succeeded
Triggered when money arrives — an invoice is paid, or the customer buys something in the customer portal.
X-Clocknext-Signature*stringt=<unix seconds>,v1=<hex HMAC-SHA256> — the HMAC of ${t}.${rawBody} keyed with the endpoint's signing secret. See Verify the signature.
X-Clocknext-Event-Id*stringThe event's id — the same as id in the body, and the same on every retry.
X-Clocknext-Event-Type*stringThe event name — the same as event_type in the body.
application/json- body
id*stringevt_ + 32 hex characters. Unique per event, and the same on every retry of it — use it to skip duplicates.
event_type*stringAlways payment.succeeded.
triggered_at*stringWhen the event was triggered (ISO 8601).
date-timedata*The customer, the payment, and the invoice or the portal item it paid for.
Answer any 2xx within 5 seconds; the body is ignored. Anything else counts as failed and is retried.
{ "id": "evt_4869ad0e4916fba0fedcc0f651361755", "event_type": "payment.succeeded", "triggered_at": "2026-11-03T13:48:09.705Z", "data": { "customer": { "id": "cus_abc123", "name": "Acme Corp" }, "payment": { "number": "PAY-0012", "amount": 118, "currency_code": "usd", "display_amount": 118, "display_currency_code": "usd", "method": "STRIPE", "reference": "pi_3P0abc", "automatic": true, "paid_at": "2026-11-03T13:48:09.000Z" }, "invoice": { "id": "inv_def456", "number": "INV-0042" }, "item": null }}{ "X-Clocknext-Signature": "t=1791367200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd", "X-Clocknext-Event-Id": "evt_4869ad0e4916fba0fedcc0f651361755", "X-Clocknext-Event-Type": "payment.succeeded"}Types
Every object type on this page, with its fields.
PaymentSucceededEvent
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | evt_ + 32 hex characters. Unique per event, and the same on every retry of it — use it to skip duplicates. |
event_type | string | yes | Always payment.succeeded. |
triggered_at | string | yes | When the event was triggered (ISO 8601). |
data | PaymentSucceededData | yes | The customer, the payment, and the invoice or the portal item it paid for. |
PaymentSucceededData
The data of payment.succeeded: the customer, the payment and what it paid for. Exactly one of invoice (an invoice was paid) and item (a portal purchase) is set.
| Field | Type | Required | Description |
|---|---|---|---|
customer | WebhookCustomer | yes | The customer the event is about. |
payment | object | yes | The money that arrived. |
invoice | WebhookInvoiceRef | null | yes | The invoice that was paid. Null for a portal buy. |
item | object | null | yes | What the customer bought in the portal. Null for an invoice payment. |
WebhookCustomer
The customer the event is about.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The customer's Clocknext id. |
name | string | yes | The customer's name. |
PaymentSucceededData.payment
The money that arrived.
| Field | Type | Required | Description |
|---|---|---|---|
number | string | null | yes | The payment's number. |
amount | number | yes | The amount paid, in USD. |
currency_code | string | yes | Always usd — amount is in USD. |
display_amount | number | yes | The same as amount, in USD (Clocknext converts no money). |
display_currency_code | string | yes | Always usd. |
method | string | null | yes | STRIPE or PADDLE for a gateway, or the method recorded by hand, such as BANK_TRANSFER. |
reference | string | null | yes | The payment gateway's id for the payment, or the reference typed with a payment recorded by hand. |
automatic | boolean | yes | True when a saved card was charged automatically for the invoice. |
paid_at | string | null | yes | When it was paid (ISO 8601). |
WebhookInvoiceRef
The invoice the payment is for.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The invoice's id. |
number | string | yes | The invoice's number. |
PaymentSucceededData.item
| Field | Type | Required | Description |
|---|---|---|---|
type | "wallet" | "credit" | "outcome" | "unit" | yes | What was bought. |
name | string | yes | The credit, outcome or unit bought, or Wallet top-up. |
quantity | number | null | yes | How many were bought. Null for a wallet top-up. |