Webhooks: order events your systems can trust

When an order comes in, a lot of other things need to know about it. The print queue should get the job. The accounting system should record the sale. Someone on Slack might like a ping. Webhooks are how DesignMint Commerce tells them, automatically, the moment it happens.

Think of a webhook as a doorbell. Instead of your systems asking DesignMint every few minutes whether anything is new, DesignMint rings the bell: it sends a message to an address you choose whenever something happens, like a new order or an updated product.

The plugin that lasted five days

We started with an off-the-shelf webhook plugin. It lasted five days. It couldn’t sign messages, so a receiver had no way to know a message really came from us. It never retried a failed delivery. Worst of all, it counted any request that didn’t crash as delivered, so a 404 (page not found) or a 500 (server error) showed up as a success. You’d think your print queue had the order when it never arrived.

So we built our own. An endpoint can listen to any of 14 events, every endpoint has its own signing secret, failed deliveries are retried, and every attempt is written to a delivery log you can read.

How a delivery works

1. Something happens, say an order is placed. If no endpoint is listening for that event, DesignMint Commerce stops right there and does no extra work.
2. DesignMint gathers the data each endpoint asked for. Endpoints can choose which fields they want, down to specific metadata, and endpoints that asked for the same fields share one lookup.
3. The message is signed. DesignMint makes an HMAC, a fingerprint built from the exact bytes of the message and the endpoint’s secret, and sends it in an X-Webhook-Signature header, as sha256= followed by the fingerprint.
4. Your system makes the same fingerprint with the same secret. If the two match, the message is genuine and wasn’t changed on the way.
5. Every attempt is logged with its status, timing, the request and the first 4,000 characters of the response. The history stays even if you delete the endpoint later.
6. If a delivery fails, DesignMint tries again, five minutes apart by default. Retries resend the original message, so your system sees the order exactly as it was when the event happened.

The small details that prevent confusing bugs

• The list of events lives in one place, used by both the settings screen and the sender. If the two ever drifted apart, you could subscribe to an event that never fires.
• Some order events carry two ids: the order’s id, and the id of the change being made to it. Grabbing the wrong one fetches the wrong record, so each event says exactly which id to use.
• Responses are always read as plain text. Otherwise an error page that claims to be data would be logged as a network failure, hiding the real message.
• Viewing the delivery history is its own permission, separate from managing endpoints, because the history contains full order details.

What we learned

• “No error” isn’t the same as “delivered”. Always check the status code.
• Sign the exact bytes you send. Anything else invites mismatches.
• Keep a log people can read. Most webhook problems are solved by looking at what was sent and what came back.

Common questions

What is a webhook?

An automatic message DesignMint Commerce sends to a web address you choose whenever something happens, like a new order, so your other systems can react straight away.

How do I know a webhook really came from DesignMint?

Every message is signed with your endpoint’s secret, which you see in full only once, when you create the endpoint. Work out an HMAC-SHA256 of the raw message body using the same secret, and compare it with the value after sha256= in the X-Webhook-Signature header. If they match, the message is genuine.

What happens if my server is down?

The delivery fails, it’s logged, and DesignMint tries again, five minutes apart by default. You can also retry any failed delivery yourself from the Activity tab.