Glossary · Payments

What is Signed webhook?

A webhook is the server-to-server tap on the shoulder: when an event happens, payment seen, confirmed, completed, the platform POSTs the fact to your endpoint instead of waiting for you to ask. Polling is checking the mailbox; webhooks are the mail arriving.

The 'signed' part is what makes it infrastructure rather than a suggestion: each payload carries a cryptographic signature your server verifies before acting, because an endpoint that trusts anonymous POSTs is an endpoint anyone can lie to.

How Signed webhook works

A webhook is the platform calling your server when something happens: an HTTP POST describing the event, delivered to an endpoint you register. Where polling asks are we there yet on a timer, the webhook is the tap on the shoulder at the moment of arrival. Payment events, confirmation transitions, payout completions, all arrive as they occur.

The mechanics that distinguish serious webhook systems: signatures, so your endpoint can verify the call genuinely came from the platform and not an attacker crafting events; retries with backoff, because your server will occasionally be down at the exact moment money moves; and ordering tolerance, because distributed systems occasionally deliver out of sequence and your handler should key on event identity rather than arrival order.

The handler contract that ages well is small: verify the signature, record the event keyed by its identifier, act once, respond quickly. Heavy work happens after acknowledgment, on your schedule, against the recorded event rather than the live request.

A note on idempotency economics: handling the same event twice is the classic silent bug, and the cure is the event identifier as the ledger's uniqueness key. The first delivery acts; the second discovers the key exists and no-ops. That single constraint converts an entire class of double-fulfillment incidents into a log line.

Signed webhook in practice

A payment confirms on-chain and the merchant's endpoint receives the signed event: reference, asset, amount, transaction hash, confirmation state. The handler verifies, records, queues fulfillment, and answers in milliseconds.

Signed webhook on U.CASH

U.CASH fires signed webhooks on every payment state change against your confirmation policy, so inventory, access, and ledgers update themselves with verified events, no polling loops.

Webhooks are how payments become operations: fulfillment, license delivery, ledger updates, all triggered by the money's actual state rather than a cron's guess. U.CASH events are signed and delivered with retries; the docs specify the verification handshake. On observability: log every delivery with its signature verification result and event identifier, and alert on verification failures loudly. The webhook layer is where money state enters your systems, and its logs are the first place an incident investigation will look.

Related payments terms

Payment railFiat on-rampCheckout embed

See also

Confirmation policyCheckout embed

Signed webhook: FAQ

What if my endpoint is down when the webhook fires?
Retries with backoff are the platform's job; idempotency, keying on the event id, is yours, so a redelivered event updates once, not twice.
Why verify the signature?
Because your endpoint is public: anyone who finds it can POST a fake 'payment completed'. The signature is the difference between acting on an event and acting on a rumor.
How do I verify a webhook is genuine?
Check the signature header against the payload using your endpoint's secret. Reject anything unsigned; a validatable call is the difference between an event and an attack.
What if my server misses an event?
Retries with backoff re-deliver, and event history remains queryable as a backstop. Keying handlers on event identifiers makes redelivery harmless.
Should I do work inside the webhook handler?
Acknowledge fast, then process. The handler's job is to capture the event durably; the fulfillment pipeline does the rest on its own schedule.
Keep reading

The glossary, A to Z

Every term behind the rails, the assets, and the settlement.