Webhooks you can trust, and cannot lose

A webhook is a promise that your software will find out before your customer does. That promise is worth exactly as much as your ability to trust the message and to survive missing one.

Trusting it: two signatures

Every delivery carries two independent proofs.

The first is an HMAC-SHA256 over the timestamped body, using the secret belonging to your endpoint. If you can verify it, the message came from someone holding that secret and the body has not been altered.

The second is an Ed25519 signature from the platform's own key, which you fetch from a public registry that supports rotation. This one does not depend on your endpoint secret at all, which matters if that secret has ever been in a place you are no longer sure about.

Verify either. Verify both. Then reject anything whose timestamp is older than five minutes, and replay is closed.

Surviving it: retries and ids

Delivery is at-least-once. We say that plainly because it is true, and because the alternative claim is marketing.

Your server will be down sometimes. Deployments happen. When a delivery fails, it is retried on a published schedule stretching across 24 hours — not dropped because you were restarting.

The consequence of at-least-once is that you will occasionally receive the same event twice. Every event carries an id. Keep the ids you have processed and ignore repeats, and you have turned at-least-once delivery into exactly-once processing, which is the thing you actually wanted all along.

Answer fast, work slowly

Acknowledge the delivery quickly, then do your work. If you mark the order, email the customer and update the warehouse before replying, a slow step somewhere in that chain turns into a retry, which turns into a duplicate, which turns into a second email.

Take the event, store it, reply, and process from your own queue.

Replay is yours

Anything can be replayed from the dashboard. If you shipped a bug that silently dropped an hour of events, you do not need to ask anyone for help — you replay the window yourself.

Before your server exists

The awkward part of any integration is that you need to see a real event to write the handler, and you need the handler to receive a real event.

There is a built-in inbox. Events for your account land somewhere you can read them, so you can look at the exact shape of a genuine event — the real fields, the real values — before writing a line of code against it.

What you can check

These are facts about the running platform, not adjectives. Each one is visible in the product, in the API reference or in the ledger.

• Two signatures per delivery: an HMAC-SHA256 over the timestamped body with your endpoint secret, and an Ed25519 signature from the platform key registry.
• Retries follow a published schedule across 24 hours; deliveries are not dropped because your server was restarting.
• Every event carries an id so a repeated delivery can be recognised and ignored.
• A built-in inbox receives events for an account that has nowhere to host an endpoint yet, so the integration can be built before the server exists.

What it costs

Included. There is no per-delivery charge.

Is it switched on?

Whether this is available depends on the authorisations in place and on what the administrator of a given deployment has switched on. That changes, and an article does not — so the live answer lives on the feature page, which reads it from the platform itself: Signed webhooks on the features page.

Read next

• The gateway API — Three calls and a webhook.
• Connected accounts — Onboard your customers by API. Hand over when they are ready.