Skip to Content
Developers

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.

  1. You run an HTTPS endpoint, such as https://example.com/weerom/webhooks, that follows the rules for an address.
  2. An administrator of the shop opens Settings, then Features, then Connections, and scrolls to Updates for other software.
  3. They paste your address under Web address, switch on the updates you need, and press Add the address.
  4. 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.
  5. 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

EventThe admin calls itWeerOm sends it when
booking.createdBooking madeA booking is made: online, by staff in the agenda, or through POST /bookings.
booking.updatedBooking changedA booking moves to another time or staff member, changes service, or staff mark it completed, a no-show or open again.
booking.cancelledBooking cancelledA booking is cancelled, by the customer, by staff or through POST /bookings/{id}/cancel.
payment.completedPayment notedStaff 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.cancelled only, never booking.updated as well.
  • Noting a payment sends payment.completed only. The booking's payment field changes, but no booking.updated goes 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:

FieldMeaning
idThe event's id: evt_ and 32 hex characters. Every address that gets this event sees the same id, and a retry keeps it.
typeThe event, such as booking.created, or test.
created_atWhen the event happened, ISO 8601 in UTC.
data.objectThe 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

HeaderValue
Content-Typeapplication/json
User-AgentWeerOm-Webhooks/1
WeerOm-EventThe event, such as payment.completed, or test.
WeerOm-DeliveryThe id of this delivery to this address, a UUID. A retry keeps it.
WeerOm-Signaturet=<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:

  1. 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.
  2. Split the header on , and each part on the first =, to get t and v1.
  3. Refuse the message when t is more than 300 seconds from your clock. A message someone recorded and sends again later fails here.
  4. Compute the HMAC-SHA256 of <t>.<raw body> with the secret, as hex.
  5. Compare it with v1 in constant time, with timingSafeEqual, hash_equals or hmac.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.

InputValue
Secretwhsec_5c1e9a7f3b2d4c6e8a0f1b3d5e7c9a2b4d6f8e0a1c3b5d7f9e2a4c6b8d0f1e3a
Body{"created_at":"2026-11-22T09:00:00.000Z","data":{"object":{"object":"test"}},"id":"evt_c4e6a8b0d2f41a3c5e7b9d1f3a5c7e9b","type":"test"}
Headert=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:

AttemptWaits after the attempt before
1None. It runs a moment after the change.
21 minute
35 minutes
430 minutes
52 hours
66 hours
724 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/16 and 169.254.0.0/16. In IPv6, only global addresses pass.
  • WeerOm connects to the exact address it checked, and sends your hostname in the Host header 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:

UseWhen
WebhooksYou 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_afterA 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.
BothYou 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.

On this page