Zum Hauptinhalt springen

Booking-Webhooks

Booking-Webhooks senden einen signierten POST an einen HTTPS-Endpunkt unter Ihrer Kontrolle, sobald ein Booking in Ihrem Workspace den Status wechselt — erstellt, bestätigt, storniert, umgeplant, abgelehnt, neu zugewiesen oder als No-Show markiert. Diese Seite behandelt die Event-Liste, die Payload, die Header, die Signaturprüfung und den Delivery-/Retry-Vertrag. Für die schreibgeschützte Bookings-API und eine schnelle Orientierung beginnen Sie mit der Bookings-Einführung.

hinweis

Webhook-Abonnements werden in den Bookings-Einstellungen der Copera-App von einem Workspace-Administrator konfiguriert — sie werden nicht über die Public API erstellt oder verwaltet. Jedes Abonnement hat eine Empfänger-URL, eine Menge von Events und ein Signing-Secret.

Events​

EventWird ausgelöst, wenn
booking.createdEin Booking wird erstellt (pending oder confirmed).
booking.confirmedEin Booking wird bestätigt.
booking.cancelledEin Booking wird storniert.
booking.rescheduledEin Booking wird auf eine neue Zeit umgeplant.
booking.declinedEin ausstehendes Booking wird vom Host abgelehnt.
booking.reassignedDer Host eines Bookings wird neu zugewiesen (Round-Robin).
booking.no_showEin No-Show für Host oder Booker wird erfasst.

Ein Abonnement empfängt nur die enthaltenen Events und nur, solange es aktiv ist.

Payload​

Jede Delivery ist ein POST mit JSON-Body:

{
  "event": "booking.confirmed",
  "createdAt": "2026-07-06T09:00:00.000Z",
  "data": {
    "id": "665f…",
    "status": "CONFIRMED",
    "bookingTypeId": "665f…",
    "bookingTypeTitle": "Intro Call",
    "start": "2026-07-08T15:00:00.000Z",
    "end": "2026-07-08T15:30:00.000Z",
    "durationMinutes": 30,
    "timezoneAtBooking": "America/Sao_Paulo",
    "hosts": [{ "userId": "665f…", "role": "ORGANIZER" }],
    "booker": {
      "name": "Alice Booker",
      "email": "[email protected]",
      "phone": "+15551234567",
      "timezone": "America/Sao_Paulo",
      "locale": "en"
    },
    "guests": [],
    "answers": [{ "questionId": "q1", "label": "Topic", "value": "Pricing" }],
    "location": { "type": "MEETING_CHANNEL" }
  }
}

Der Block data ist die Booking-Daten Ihres eigenen Workspace, daher sind Kontaktdaten des Bookers enthalten. Sensible interne Felder werden nie gesendet.

Webhook-Event mit der Public API korrelieren​

Die Webhook-Payload trägt data.id. Übergeben Sie sie direkt an GET /public/v1/bookings/{id}, um die vollständigen Booking-Details zu holen:

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.copera.ai/public/v1/bookings/${data.id}"

Nutzen Sie denselben Wert data.id mit einer authentifizierten Bookings-API-Anfrage, wenn Sie Webhook-Events mit den vollen Booking-Details korrelieren wollen.

HeaderWert
X-Copera-EventDer Event-String (z. B. booking.confirmed).
X-Copera-Signaturesha256=<hex> — HMAC-SHA256 des rohen Request-Body mit Ihrem Abonnement-Secret.
X-Copera-Webhook-VersionDie Payload-Vertragsversion (derzeit 1).

Signatur prüfen​

Berechnen Sie den HMAC-SHA256 des rohen Request-Body (vor dem JSON-Parsing) mit Ihrem Abonnement-Secret und vergleichen Sie ihn zeitkonstant mit dem Hex in X-Copera-Signature:

import { createHmac, timingSafeEqual } from "node:crypto";

function isValidSignature(rawBody, header, secret) {
  const expected =
    "sha256=" + createHmac("sha256", secret).update(rawBody, "utf8").digest("hex");
  const a = Buffer.from(header);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Delivery und Retries​

  • Antworten Sie mit 2xx, um den Empfang zu bestätigen.
  • Ein 4xx gilt als endgültige Ablehnung — Copera retryt nicht.
  • Ein 5xx, Netzwerkfehler oder Timeout wird mit exponentiellem Backoff erneut versucht (insgesamt 3 Versuche). Machen Sie Ihren Empfänger idempotent — dasselbe Event kann mehrfach zugestellt werden.
  • Empfänger-URLs müssen öffentliche HTTPS-Endpunkte sein; private oder interne Adressen werden abgelehnt.

Referenz​