# Webhooks

Source: https://developers.weerom.com/docs/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](#polling-as-the-fallback) 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](#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](#the-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.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:

| 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](https://developers.weerom.com/docs/reference/bookings/getBooking) and [Get a payment](https://developers.weerom.com/docs/reference/payments/getPayment) 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

```json
{
  "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": "lotte@example.com",
        "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

```json
{
  "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": "lotte@example.com",
        "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:

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.

```js tab="JavaScript"
// 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);
```

```php tab="PHP"
<?php
// PHP 8. Point your web server at this file.
const TOLERANCE_SECONDS = 300;

function weeromVerify(string $rawBody, string $header, string $secret): bool
{
    $parts = [];
    foreach (explode(',', $header) as $part) {
        $pair = explode('=', $part, 2);
        if (count($pair) === 2) {
            $parts[$pair[0]] = $pair[1];
        }
    }
    if (!isset($parts['t'], $parts['v1']) || !ctype_digit($parts['t'])) {
        return false;
    }
    if (abs(time() - (int) $parts['t']) > TOLERANCE_SECONDS) {
        return false;
    }
    $expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);
    return hash_equals($expected, $parts['v1']);
}

$raw = file_get_contents('php://input');
$header = $_SERVER['HTTP_WEEROM_SIGNATURE'] ?? '';

if (!weeromVerify($raw, $header, getenv('WEEROM_WEBHOOK_SECRET'))) {
    http_response_code(400);
    exit;
}

$message = json_decode($raw, true);
// Store it and answer. Do the slow work later, from your own queue.
saveMessage($message);
http_response_code(200);
```

```python tab="Python"
# Python 3 with Flask: pip install flask
import hashlib
import hmac
import os
import time

from flask import Flask, request

SECRET = os.environ["WEEROM_WEBHOOK_SECRET"]
TOLERANCE_SECONDS = 300

app = Flask(__name__)

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(part.split("=", 1) for part in header.split(",") if "=" in part)
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or not v1:
        return False
    if abs(time.time() - int(t)) > TOLERANCE_SECONDS:
        return False
    expected = hmac.new(
        secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, v1)

@app.post("/weerom/webhooks")
def weerom_webhooks():
    raw = request.get_data()
    if not verify(raw, request.headers.get("WeerOm-Signature", ""), SECRET):
        return "", 400
    # Store it and answer. Do the slow work later, from your own queue.
    save_message(request.get_json())
    return "", 200
```

`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](#polling-as-the-fallback).

## 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:

```json
{
  "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](https://developers.weerom.com/docs/pagination#sync-only-what-changed) 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.
