Webhooks

Register endpoints that receive signed notifications when a customer's wallet balance changes or drops to a low-balance level.

Webhooks lets your own backend hear about wallet changes as they happen. You register an endpoint — a URL on your side — and pick which events it receives. Clocknext then POSTs a signed JSON message to that URL every time one of those events is triggered, and keeps a log of every delivery attempt so you can see what was sent, what your server answered, and retry anything that failed.

Today there are two events, both about a customer's wallet:

Event	Triggered when
`wallet.balance.update`	A customer's wallet balance increased or decreased.
`wallet.balance.drop`	A customer's wallet balance dropped to or below their low-balance alert level, or this endpoint's threshold if they have none.

High volume

wallet.balance.update is also triggered by every usage charge on the wallet, so an endpoint subscribed to it can receive many events.

Each event's payload is on its page in the API reference; for the headers and how to verify the signature, see Webhooks.

What you can do here

Add an endpoint: a name, a URL, and the events it should receive.
Set a USD threshold for wallet.balance.drop.
Copy or reveal an endpoint's signing secret, and rotate it.
Edit an endpoint's name, URL, events and threshold.
Disable an endpoint temporarily, or delete it.
Browse each endpoint's delivery history, view the exact payload sent, and retry a failed delivery.

Owner or admin only

Adding, editing, disabling, deleting, rotating secrets, revealing secrets, and retrying deliveries are available to owners and admins. Members can see the endpoints but not change them.

The endpoint's Name, with an edit button and a Disabled badge when it's off. Endpoints created before names existed show "—".
A Failing since notice when the most recent deliveries have been failing — it shows when the current run of failures started and disappears after the next successful delivery.
Signing Secret — masked as whsec_•••• plus its last four characters. Use the eye button to reveal the full value and the copy button to copy it.
Subscribed events — the events this endpoint receives; the threshold is shown next to wallet.balance.drop (e.g. wallet.balance.drop · $50).
Message Attempts — the delivery history (below).

Message Attempts

One row per delivery attempt, newest first, filterable by All, Success, or Failed, with Load more for older rows.

Column	Shows
Timestamp	When the attempt was made, to the millisecond.
Event Type	The event name, with `· attempt N` when this was a retry.
Message ID	The event's `evt_…` id. It's the same on every retry of one event.
Status	Success (your server answered 2xx) or Failed (anything else, or no answer).
Action	Raw data shows the exact JSON body sent. Retry (failed rows only) sends it again.

Adding an endpoint

Press Add webhook.
Give it a Name.
Enter your Webhook URL, e.g. https://your.app/webhooks/clocknext.
Tick the events you want. For wallet.balance.drop, enter the Threshold (USD).
Press Add webhook.
The Your signing secret dialog shows the endpoint's secret (it starts with whsec_). Copy it into your server's configuration — you need it to verify that messages really come from Clocknext. You can also reveal it later from the endpoint's detail page.

How the low-balance alert works

wallet.balance.drop has two levels, and the customer's own comes first:

The customer has their own level — set on the customer's Manage tab (see Wallet) or with the API. Only that level is used: one event goes to every endpoint subscribed to it, whatever each endpoint's threshold is.
The customer has none — each endpoint uses its own threshold, and each is triggered on its own crossing.

Either way it is triggered when a single balance change takes the wallet from above the level to at or below it, once per drop — not on every charge while the balance stays low, and again only after the balance goes back above the level and drops again.

Managing an endpoint

Edit — change the name, the URL, the selected events and the threshold. The new event list replaces the old one.
Disable Endpoint — stops deliveries. Events that happen while it's disabled are not sent, and are not sent later when you re-enable it. Enable Endpoint resumes deliveries and clears the Failing since notice.
Rotate secret — issues a new secret and shows it in the Your signing secret dialog. Every delivery from that moment on, including retries, is signed with the new secret, so update your server straight away.
Delete — after confirming, removes the endpoint, its secret, and its delivery history. This can't be undone.
Retry — on a failed row in Message Attempts, sends the same payload (same Message ID) again and adds a new row with the result.

Webhooks in the API reference — events, payloads, headers, and signature verification.
Customer detail — a customer's wallet balance and history.
API Keys — the key your backend uses to call the Clocknext API.

Today there are two events, both about a customer's wallet:

Event	Triggered when
`wallet.balance.update`	A customer's wallet balance increased or decreased.
`wallet.balance.drop`	A customer's wallet balance dropped to or below their low-balance alert level, or this endpoint's threshold if they have none.

High volume

wallet.balance.update is also triggered by every usage charge on the wallet, so an endpoint subscribed to it can receive many events.

Each event's payload is on its page in the API reference; for the headers and how to verify the signature, see Webhooks.

What you can do here

Add an endpoint: a name, a URL, and the events it should receive.
Set a USD threshold for wallet.balance.drop.
Copy or reveal an endpoint's signing secret, and rotate it.
Edit an endpoint's name, URL, events and threshold.
Disable an endpoint temporarily, or delete it.
Browse each endpoint's delivery history, view the exact payload sent, and retry a failed delivery.

Owner or admin only

Adding, editing, disabling, deleting, rotating secrets, revealing secrets, and retrying deliveries are available to owners and admins. Members can see the endpoints but not change them.

The endpoint's Name, with an edit button and a Disabled badge when it's off. Endpoints created before names existed show "—".
A Failing since notice when the most recent deliveries have been failing — it shows when the current run of failures started and disappears after the next successful delivery.
Signing Secret — masked as whsec_•••• plus its last four characters. Use the eye button to reveal the full value and the copy button to copy it.
Subscribed events — the events this endpoint receives; the threshold is shown next to wallet.balance.drop (e.g. wallet.balance.drop · $50).
Message Attempts — the delivery history (below).

Message Attempts

One row per delivery attempt, newest first, filterable by All, Success, or Failed, with Load more for older rows.

Column	Shows
Timestamp	When the attempt was made, to the millisecond.
Event Type	The event name, with `· attempt N` when this was a retry.
Message ID	The event's `evt_…` id. It's the same on every retry of one event.
Status	Success (your server answered 2xx) or Failed (anything else, or no answer).
Action	Raw data shows the exact JSON body sent. Retry (failed rows only) sends it again.

Adding an endpoint

Press Add webhook.
Give it a Name.
Enter your Webhook URL, e.g. https://your.app/webhooks/clocknext.
Tick the events you want. For wallet.balance.drop, enter the Threshold (USD).
Press Add webhook.
The Your signing secret dialog shows the endpoint's secret (it starts with whsec_). Copy it into your server's configuration — you need it to verify that messages really come from Clocknext. You can also reveal it later from the endpoint's detail page.

How the low-balance alert works

wallet.balance.drop has two levels, and the customer's own comes first:

The customer has their own level — set on the customer's Manage tab (see Wallet) or with the API. Only that level is used: one event goes to every endpoint subscribed to it, whatever each endpoint's threshold is.
The customer has none — each endpoint uses its own threshold, and each is triggered on its own crossing.

Managing an endpoint

Edit — change the name, the URL, the selected events and the threshold. The new event list replaces the old one.
Disable Endpoint — stops deliveries. Events that happen while it's disabled are not sent, and are not sent later when you re-enable it. Enable Endpoint resumes deliveries and clears the Failing since notice.
Rotate secret — issues a new secret and shows it in the Your signing secret dialog. Every delivery from that moment on, including retries, is signed with the new secret, so update your server straight away.
Delete — after confirming, removes the endpoint, its secret, and its delivery history. This can't be undone.
Retry — on a failed row in Message Attempts, sends the same payload (same Message ID) again and adds a new row with the result.

Webhooks in the API reference — events, payloads, headers, and signature verification.
Customer detail — a customer's wallet balance and history.
API Keys — the key your backend uses to call the Clocknext API.

What you can do here

On this page

Endpoints list

Add / edit webhook

Endpoint detail (`/settings/webhooks/[id]`)

Message Attempts

Adding an endpoint

Managing an endpoint

On this page

Webhooks

What you can do here

On this page

Endpoints list

Add / edit webhook

Endpoint detail (`/settings/webhooks/[id]`)

Message Attempts

Adding an endpoint

Managing an endpoint

On this page