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 "", 204Retries
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