Webhooks
WeerOm posts a signed JSON message to your server when a booking is made, changed or cancelled, or a payment is noted. Verify it, answer 2xx, then work.
A webhook is a POST from WeerOm to your server. When a booking is made, changed or cancelled, or staff note a payment, WeerOm sends a JSON message to every address the shop added for that event. The message holds the whole booking or payment, as GET /bookings/{id} or GET /payments/{id} would answer at that moment.
With webhooks, an invoice can exist a few seconds after the customer paid, and a calendar moves the moment the booking does. Without them, your job asks the API on a schedule. Polling below says when that still fits.
Add an address
The shop adds the address in its admin. There is no API endpoint for it, so you give the shop the address and the shop gives you the secret.
- You run an HTTPS endpoint, such as
https://example.com/weerom/webhooks, that follows the rules for an address. - An administrator of the shop opens Settings, then Features, then Connections, and scrolls to Updates for other software.
- They paste your address under Web address, switch on the updates you need, and press Add the address.
- The admin shows the Secret once. It starts with
whsec_. They copy it to you, and you store it like a password: in an environment variable or a secret store, never in source code. - They press Send a test. Your endpoint gets a test message, and the admin says whether it answered.
A shop holds up to 5 addresses. Each address has its own secret and its own set of events. The shop must be on the Premium plan, the same as for keys. A shop that leaves Premium keeps its addresses but sends nothing until it is back.
Each address can be switched off and on in the same place. Removing it stops every message at once and cannot be undone. A new address gets a new secret.
Events
| Event | The admin calls it | WeerOm sends it when |
|---|---|---|
booking.created | Booking made | A booking is made: online, by staff in the agenda, or through POST /bookings. |
booking.updated | Booking changed | A booking moves to another time or staff member, changes service, or staff mark it completed, a no-show or open again. |
booking.cancelled | Booking cancelled | A booking is cancelled, by the customer, by staff or through POST /bookings/{id}/cancel. |
payment.completed | Payment noted | Staff note a payment, or change the method or an amount of a payment they noted earlier. |
What sends nothing:
- Time staff block off for a break. It is not a booking.
- A cancellation sends
booking.cancelledonly, neverbooking.updatedas well. - Noting a payment sends
payment.completedonly. The booking'spaymentfield changes, but nobooking.updatedgoes out. - Staff clearing a payment, or saving one again without a change.
- A change to a customer. Read those with
GET /customers?updated_after=....
The message
Every message has the same four fields:
| Field | Meaning |
|---|---|
id | The event's id: evt_ and 32 hex characters. Every address that gets this event sees the same id, and a retry keeps it. |
type | The event, such as booking.created, or test. |
created_at | When the event happened, ISO 8601 in UTC. |
data.object | The booking or the payment, as the API answers it at that moment. Get a booking and Get a payment describe every field. |
WeerOm writes the body once, on one line, and sends those exact bytes on every attempt. The examples below have line breaks added.
booking.created
{
"created_at": "2026-11-18T14:02:11.412Z",
"data": {
"object": {
"cancel_reason": "",
"cancelled_at": null,
"code": "UEAMEFC9",
"comments": "",
"created_at": "2026-11-18T14:02:11.000Z",
"currency": "EUR",
"customer": {
"email": "[email protected]",
"id": "5f0c9d3a-7b2e-4c61-8a4d-9e1f3b6c2d75",
"name": "Lotte Peeters",
"phone": "+32470123456"
},
"discount_percent": 0,
"ends_at": "2026-11-21T10:15:00.000Z",
"id": "0b6f2a4e-5d1c-4f7a-9a3e-2c8d1e6f4b90",
"list_price_cents": 4000,
"locale": "nl",
"minutes": 45,
"object": "booking",
"payment": null,
"price_cents": 4000,
"service": {
"id": "c2a41f6e-8d3b-4e97-b5a0-1f7c9e2d4a68",
"name": "Knippen en baard"
},
"source": "web",
"staff_id": "8e1d5b7c-3a9f-4d20-b6c4-7a2e0f9d1c53",
"starts_at": "2026-11-21T09:30:00.000Z",
"status": "confirmed",
"updated_at": "2026-11-18T14:02:11.000Z"
}
},
"id": "evt_3f9a1c2e5b7d4a68c0e1f2a3b4c5d6e7",
"type": "booking.created"
}booking.updated and booking.cancelled carry the same booking object, with the new starts_at, staff_id, status or cancelled_at.
payment.completed
{
"created_at": "2026-11-21T10:12:40.517Z",
"data": {
"object": {
"amount_cents": 4000,
"booking_code": "UEAMEFC9",
"booking_id": "0b6f2a4e-5d1c-4f7a-9a3e-2c8d1e6f4b90",
"currency": "EUR",
"customer": {
"email": "[email protected]",
"id": "5f0c9d3a-7b2e-4c61-8a4d-9e1f3b6c2d75",
"name": "Lotte Peeters",
"phone": "+32470123456"
},
"description": "Knippen en baard",
"discount_percent": 0,
"id": "0b6f2a4e-5d1c-4f7a-9a3e-2c8d1e6f4b90",
"list_price_cents": 4000,
"method": "bancontact",
"net_cents": 3306,
"object": "payment",
"paid_at": "2026-11-21T10:12:40.000Z",
"service_id": "c2a41f6e-8d3b-4e97-b5a0-1f7c9e2d4a68",
"staff_id": "8e1d5b7c-3a9f-4d20-b6c4-7a2e0f9d1c53",
"starts_at": "2026-11-21T09:30:00.000Z",
"tip_cents": 200,
"vat_cents": 694,
"vat_percent": 21
}
},
"id": "evt_8b2e4d6f1a3c5e7092b4d6f8a1c3e5f7",
"type": "payment.completed"
}A payment's id is its booking's id. When staff correct a payment, a second payment.completed arrives with the same data.object.id, a later paid_at and the new amounts. Treat it as a change to the payment you already have, not as a new one.
Headers
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | WeerOm-Webhooks/1 |
WeerOm-Event | The event, such as payment.completed, or test. |
WeerOm-Delivery | The id of this delivery to this address, a UUID. A retry keeps it. |
WeerOm-Signature | t=<unix seconds>,v1=<signature>. See below. |
Verify the signature
Anyone can send a POST to your address. The signature proves that WeerOm sent the message and that nobody changed it on the way.
WeerOm-Signature holds two parts. t is the moment of this attempt in Unix seconds. v1 is the HMAC-SHA256, in lowercase hex, of t, a dot and the raw body, with the whole secret as the key, whsec_ included.
To check a message:
- Read the raw body as bytes, before any JSON parser touches it. A parsed and re-written body has other bytes and fails the check.
- Split the header on
,and each part on the first=, to gettandv1. - Refuse the message when
tis more than 300 seconds from your clock. A message someone recorded and sends again later fails here. - Compute the HMAC-SHA256 of
<t>.<raw body>with the secret, as hex. - Compare it with
v1in constant time, withtimingSafeEqual,hash_equalsorhmac.compare_digest. A plain==stops at the first wrong character, and the time it takes tells an attacker how much of the signature was right.
Only parse the JSON once all of that passed.
// Node 22, no packages. Run with WEEROM_WEBHOOK_SECRET=whsec_... node webhooks.js
import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";
const SECRET = process.env.WEEROM_WEBHOOK_SECRET;
const TOLERANCE_SECONDS = 300;
export function verify(rawBody, header, secret, nowMs = Date.now()) {
const parts = {};
for (const part of (header ?? "").split(",")) {
const at = part.indexOf("=");
if (at > 0) parts[part.slice(0, at)] = part.slice(at + 1);
}
const t = Number(parts.t);
if (!Number.isInteger(t) || !parts.v1) return false;
if (Math.abs(nowMs / 1000 - t) > TOLERANCE_SECONDS) return false;
const expected = createHmac("sha256", secret)
.update(`${t}.`)
.update(rawBody)
.digest();
const given = Buffer.from(parts.v1, "hex");
return given.length === expected.length && timingSafeEqual(given, expected);
}
createServer((req, res) => {
const chunks = [];
req.on("data", (chunk) => chunks.push(chunk));
req.on("end", async () => {
const raw = Buffer.concat(chunks);
if (!verify(raw, req.headers["weerom-signature"], SECRET)) {
res.writeHead(400).end();
return;
}
const message = JSON.parse(raw.toString("utf8"));
// Store it and answer. Do the slow work later, from your own queue.
await saveMessage(message);
res.writeHead(200).end();
});
}).listen(3000);saveMessage(message) and save_message(message) stand for your own code: a row in a table or a job in a queue.
Check your code
These values give a known signature. Your verify should return true for them when you pass t as the current time, and false once you change one character of the body.
| Input | Value |
|---|---|
| Secret | whsec_5c1e9a7f3b2d4c6e8a0f1b3d5e7c9a2b4d6f8e0a1c3b5d7f9e2a4c6b8d0f1e3a |
| Body | {"created_at":"2026-11-22T09:00:00.000Z","data":{"object":{"object":"test"}},"id":"evt_c4e6a8b0d2f41a3c5e7b9d1f3a5c7e9b","type":"test"} |
| Header | t=1795338000,v1=732c16f54332b87717f1cd6dbe9183242de7ad029c2bc36d9b6a059b36a503f6 |
1795338000 is 2026-11-22 09:00 UTC, so the age check refuses it on any other day. Skip that one check while you test with it.
Answer fast, then do the work
- Any 2xx status counts as delivered. WeerOm never reads the body of your answer.
- An attempt that gets no answer within 10 seconds counts as failed, even when your server finishes the work later.
- A redirect counts as failed. WeerOm does not follow it, so give the shop the final address.
- Store the message, answer 200, and do the slow part, such as calling Billit or Google Calendar, from your own queue afterwards.
Retries
The first attempt runs right after the change. When it fails, WeerOm tries again on this schedule:
| Attempt | Waits after the attempt before |
|---|---|
| 1 | None. It runs a moment after the change. |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 6 hours |
| 7 | 24 hours |
Retries run once a minute and send up to 25 messages per shop per run, so a retry can start a minute or more after its time. After the seventh failure, about 33 hours after the change, WeerOm gives up on that message. It does not send it again, and there is no way to ask for it later. Read what you missed from the API: see polling.
The same message twice, and the order
Most messages arrive once. A few arrive twice: when your server did the work but answered after 10 seconds, or when WeerOm stopped between sending and noting your answer. Store each id you handled and skip one you have seen.
Messages can also arrive out of order. A retry of an older change can land after a newer one. Compare data.object.updated_at for a booking, or data.object.paid_at for a payment, with what you stored, and keep the newest.
When the order matters to you, read the object again with GET /bookings/{id} or GET /payments/{id} before you act. That needs a key as well as the secret.
When an address is switched off
An address that has failed every attempt for 3 days is switched off. The 3 days count from the first failure since the last delivered message, and any 2xx resets them. Once it is off:
- No new messages are made for it, and the ones still waiting are dropped.
- The admin shows "Not answering since" and the date of that first failure.
- Switching it on again in the admin starts a fresh count. It does not send what was dropped.
A shop that leaves the Premium plan sends nothing either. Messages still waiting are dropped. The addresses stay and send again once the shop is on Premium.
Rules for an address
WeerOm checks the address when the shop adds it, and again before every attempt. An address that fails a check is refused, or its attempt fails.
- It starts with
https://. The certificate must be valid for the hostname. A self-signed certificate fails. - No user name or password in it, and at most 500 characters.
- The port is 443, 80 or one above 1023.
- The hostname resolves, and every address it resolves to is on the public internet. Private and local ranges are refused, such as
10.0.0.0/8,127.0.0.0/8,172.16.0.0/12,192.168.0.0/16and169.254.0.0/16. In IPv6, only global addresses pass. - WeerOm connects to the exact address it checked, and sends your hostname in the
Hostheader and the TLS handshake.
To test on your own computer, put a tunnel with a public HTTPS address in front of it.
The test message
Send a test in the admin posts one message to that address and waits for the answer:
{
"created_at": "2026-11-22T09:00:00.000Z",
"data": { "object": { "object": "test" } },
"id": "evt_c4e6a8b0d2f41a3c5e7b9d1f3a5c7e9b",
"type": "test"
}It carries WeerOm-Event: test and a signature like any other message. It is sent once, without retries, also to an address that is switched off. A failed test does not count toward switching the address off. Answer it with 2xx like the rest, and ignore its content.
Polling as the fallback
Webhooks and the API work together. Each fits a different job:
| Use | When |
|---|---|
| Webhooks | You need to act within seconds of a change: an invoice per payment, a calendar that follows the agenda, a message in the staff chat. |
Polling with updated_after or paid_after | A run once an hour or once a night is enough, such as a sheet or a newsletter list. Or nobody can add an address: a script on a laptop, a tool without a public HTTPS address. |
| Both | You cannot lose a change. Act on each webhook, and run a sync every few hours that reads what changed since its last run. It catches messages lost while your server was down for more than 33 hours. |
Pagination has the polling loop.
Limits
- No API endpoint adds, lists or removes an address. The shop does that in the admin.
- The message does not name the shop. Software that serves several shops gives each one its own address, such as
https://example.com/weerom/noord, and checks each message with that shop's secret. - No event for customers, services or staff. Poll
GET /customers?updated_after=...for customers. - No replay. A message that failed all 7 attempts is gone. The API still holds the current state.
- The message holds the object as it was when the change happened, not what changed. Compare it with your own copy to see that.