Webhooks
Erhalten Sie eine HTTP-Anfrage in dem Moment, in dem ein Termin erstellt, bestätigt, verschoben, storniert oder abgeschlossen wird, und verbinden Sie BookifyLabs mit Ihren eigenen Systemen.
Endpunkt hinzufügen
- Öffnen Sie als Inhaber die Einstellungen im Unternehmensbereich und suchen Sie die Karte Webhooks.
- Klicken Sie auf Endpunkt hinzufügen und geben Sie eine öffentliche https://-URL ein. Private Netzwerkadressen und localhost werden abgelehnt.
- Kopieren Sie das nach der Erstellung angezeigte Signaturgeheimnis (Signing Secret). Es beginnt mit
whsec_und wird nur ein einziges Mal angezeigt. - Senden Sie ein Testereignis, indem Sie einen Termin erstellen, und prüfen Sie anschließend die Liste Zustellungen.
Sie können bis zu 5 Endpunkte pro Unternehmen haben. Jeder Endpunkt kann pausiert und fortgesetzt, seine URL geändert, sein Geheimnis erneuert oder zusammen mit seiner Zustellungshistorie gelöscht werden.
Ereignisse
| Ereignis | Gesendet wenn |
|---|---|
appointment.created | Eine Buchung vorgenommen wird – online, durch Booky oder durch Ihr Team. |
appointment.confirmed | Ein ausstehender Termin bestätigt wird. |
appointment.rescheduled | Sich die Uhrzeit oder die Fachkraft ändert. |
appointment.cancelled | Der Termin durch Sie oder den Kunden storniert wird. |
appointment.completed | Der Termin über den Abschlussbildschirm als erledigt markiert wird. |
Anfrageformat
Jede Zustellung ist ein POST mit einem JSON-Body. Das data-Objekt ist eine Momentaufnahme des Termins zum Zeitpunkt des Ereignisses; erneute Zustellversuche senden denselben Body erneut.
POST https://example.com/hooks/bookify
Content-Type: application/json
User-Agent: BookifyLabs-Webhooks/1.0 (+https://bookifylabs.com)
X-Bookify-Event-ID: evt_3f6c…
X-Bookify-Timestamp: 1757145600
X-Bookify-Signature: 4b1d…
{
"id": "evt_3f6c…",
"type": "appointment.created",
"created_at": 1757145600,
"data": {
"appointment": { "id": 1234, "status": "booked", "start_at": "…", "…": "…" }
}
}Signatur verifizieren
Die Signatur ist ein Hex-HMAC-SHA256 über den String <timestamp>.<raw body>, verschlüsselt mit dem Geheimnis Ihres Endpunkts. Berechnen Sie diesen aus dem unparsierten Request-Body (Raw Body) vor jedem JSON-Parsing und vergleichen Sie ihn mit einer Laufzeit-konstanten Funktion (Constant-Time Function).
import crypto from "node:crypto";
function verify(rawBody, headers, secret) {
const ts = headers["x-bookify-timestamp"];
const sig = headers["x-bookify-signature"];
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // älter als 5 Minuten
const expected = crypto
.createHmac("sha256", secret)
.update(`${ts}.${rawBody}`)
.digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}- Weisen Sie Zeitstempel zurück, die älter als 5 Minuten sind, um Replay-Angriffe zu verhindern.
- Führen Sie eine Duplikatsprüfung anhand von X-Bookify-Event-ID durch: Ein erneuter Zustellversuch trägt dieselbe ID.
- Antworten Sie innerhalb von 10 Sekunden mit einem beliebigen 2xx-Statuscode. Führen Sie zeitintensive Aufgaben erst nach der Antwort aus.
Wiederholungen und Zustellungsverlauf
Eine Zustellung, die in ein Timeout läuft oder eine Antwort mit 408, 425, 429 oder einem beliebigen 5xx-Code erhält, wird alle 12 Stunden für bis zu 30 Versuche wiederholt. Weiterleitungen wird nicht gefolgt und andere 4xx-Antworten werden als endgültig behandelt. Die Tabelle Zustellungen zeigt den Status jedes Ereignisses (ausstehend, wird gesendet, erneuter Versuch, zugestellt, fehlgeschlagen), die Versuche, die gespeicherte Antwort (bis zu 4 KB) und den Zeitpunkt des nächsten Versuchs. Fehlgeschlagene oder zu wiederholende Zustellungen können mit Jetzt erneut versuchen angestoßen werden. Der Verlauf wird 30 Tage lang aufbewahrt.