Skip to content

Signed webhooks: how to verify webhook signatures

Get notified when a meeting is booked, rescheduled or cancelled, and verify each webhook signature before you trust it.

A webhook saves you from polling: Artibox Calendar sends a POST to your URL as soon as something happens. Knowing how to verify webhook signatures matters: it is the only proof the call comes from Artibox Calendar, unchanged. Webhooks come with the Team plan (pricing).

Create a subscription

curl -X POST "$RDV_API/webhook-subscriptions" \
  -H "x-api-key: $RDV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/webhooks/artibox","events":["reservation.creee","reservation.annulee"]}'

The response holds the signing secret whsec_…, shown once. An optional type_id narrows the subscription to one event type. The URL must be public https.

Events and payload

Events: reservation.creee, reservation.deplacee, reservation.annulee, reservation.constatee, sondage.vote, sondage.confirme, envoi_lien.envoye, envoi_lien.reservation_obtenue, type.cree, type.modifie, connexion_agenda.a_reconnecter, routage.soumis and test. Every delivery is {id, evenement, cree_le, organisation_id, donnees} (French keys); each event's payload is in the events reference. The envelope id is the same across subscriptions and retries: use it to drop duplicates.

Verify webhook signatures

X-Signature looks like t=1764579600,v1=5d41…: t is the Unix time of the delivery, v1 the hex HMAC-SHA256 of t + . + the raw body, keyed with your whole whsec_… secret. Compute it on the raw body, compare in constant time, and reject an old t (say five minutes).

Node.js (Express)

import crypto from "node:crypto";
import express from "express";

const app = express();
const secret = process.env.RDV_WEBHOOK_SECRET; // whsec_…

app.post("/webhooks/artibox", express.raw({ type: "application/json" }), (req, res) => {
  const fields = Object.fromEntries((req.get("X-Signature") ?? "").split(",").map((part) => part.split("=", 2)));
  const age = Math.abs(Date.now() / 1000 - Number(fields.t));
  const expected = crypto.createHmac("sha256", secret).update(`${fields.t}.${req.body}`).digest("hex");
  const valid = typeof fields.v1 === "string" && fields.v1.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(fields.v1), Buffer.from(expected));
  if (!valid || !(age <= 300)) return res.sendStatus(400);
  res.sendStatus(204);
});

PHP

<?php
$secret = getenv('RDV_WEBHOOK_SECRET'); // whsec_…
$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_SIGNATURE'] ?? ''), $fields);
$timestamp = (int) ($fields['t'] ?? 0);
$expected = hash_hmac('sha256', $timestamp . '.' . $body, $secret);
if (!hash_equals($expected, (string) ($fields['v1'] ?? '')) || abs(time() - $timestamp) > 300) {
    http_response_code(400);
    exit;
}
http_response_code(204);

Python (Flask)

import hashlib, hmac, os, time
from flask import Flask, request

app = Flask(__name__)
SECRET = os.environ["RDV_WEBHOOK_SECRET"].encode()  # whsec_…

@app.post("/webhooks/artibox")
def artibox():
    fields = dict(part.split("=", 1) for part in request.headers.get("X-Signature", "").split(",") if "=" in part)
    expected = hmac.new(SECRET, fields.get("t", "").encode() + b"." + request.get_data(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, fields.get("v1", "")) or abs(time.time() - int(fields.get("t", "0"))) > 300:
        return "", 400
    return "", 204

Retries

Answer 2xx within 10 seconds and process in the background. Anything else, a redirect or silence is a failure, retried after 1, 5, 30, 120 then 720 minutes; 20 failures in a row disable the subscription. The log keeps 30 days of deliveries, and a delivery can be replayed: see the webhooks reference. Building for several organisations? Read authentication.

Connect your tools in real time

Create your first subscription in Settings › Integrations, then send a test.

Create my account