API: Webhooks einrichten und betreiben

Webhooks senden Ereignisse aus edoobox an eine technische Empfangsadresse Ihrer Integration. Dort können Sie beispielsweise eine geänderte Buchung im CRM nachladen. Die Webhook-Verwaltung erfolgt über die API-Ressource /v2/webhook. Diese Anleitung richtet sich an die für die Integration zuständige Entwicklung.

Rolle, API-Zugang und Empfangsadresse vorbereiten

Die Einrichtung benötigt einen API-Zugang mit Schreibrecht für Webhooks; zum Rücklesen ist zusätzlich Leserecht erforderlich. Ein Schlüssel mit ausschliesslichem Leserecht kann keine neue Webhook-Konfiguration anlegen. Das vorbereitete Zapier-Recht umfasst die Webhook-Verwaltung, das WordPress-Recht erlaubt hier nur Lesen. Verwenden Sie für eine eigene Integration eine passend eingeschränkte Berechtigungsgruppe und prüfen Sie deren weitere Rechte.

Bereiten Sie eine dauerhaft erreichbare HTTPS-Adresse Ihres eigenen Servers vor, zum Beispiel https://example.org/integrationen/edoobox.
Erzeugen Sie ein eigenes zufälliges Webhook-Secret und speichern Sie es sicher beim Empfänger. Dieses Secret ist vom Secret des API-Schlüssels getrennt.
Erstellen beziehungsweise prüfen Sie den API-Zugang unter API-Schlüssel und Zugriffsrechte.
Authentifizieren Sie sich gemäss API: Erste Schritte mit dem richtigen Host, Bearer-Token und edid.
Prüfen Sie die benötigten Ressourcenrechte und die Verfügbarkeit Ihrer Integration im Konto. Ein freigegebener API-Zugang allein beschreibt noch nicht den fachlichen Umfang einer beliebigen Anbindung.

Der allgemeine API-Einrichtungsweg ist nicht mit einem Zahlungsanbieter-Webhook oder einer Scanner-Empfangsadresse zu verwechseln. Solche Verbindungen besitzen eigene Fachanleitungen und Zugangsdaten.

Webhook zunächst inaktiv anlegen

Senden Sie POST /v2/webhook mit Content-Type: application/json sowie Ihren üblichen Authorization- und edid-Headern. Der folgende Body ist ein Beispiel; ersetzen Sie Empfangsadresse und Secret durch Ihre eigenen Werte.

{
  "data": {
    "status": false,
    "url": "https://example.org/integrationen/edoobox",
    "secret": "EIGENES_ZUFAELLIGES_WEBHOOK_SECRET",
    "topics": ["post_Booking", "put_Booking"]
  }
}

Prüfen Sie HTTP-Status und error der Antwort und speichern Sie die zurückgegebene öffentliche Webhook-ID. Verwenden Sie dieselbe ID für spätere Änderungen; legen Sie bei einem unklaren Ergebnis nicht ungeprüft einen zweiten Eintrag an. Lesen Sie zunächst GET /v2/webhook/list.

Feld	Verwendung
`status`	`false` zum Vorbereiten, `true` zum Empfangen passender Ereignisse.
`url`	Technische Empfangsadresse Ihres Servers.
`secret`	Gemeinsames Secret für die HMAC-Signatur. Sicher aufbewahren; den Rücklesewert nicht als vollständige Sicherung behandeln.
`topics`	Liste der gewünschten Ereignisnamen.
`basicauth`	Optionaler zusätzlicher HTTP-Basic-Auth-Zugang des Empfängers. Nur verwenden, wenn dessen Einrichtung darauf abgestimmt ist.

Die vollständigen Feldbeschreibungen und HTTP-Operationen stehen in der API-v2-Referenz.

Topics bewusst wählen und zurücklesen

Für Buchungen sind beispielsweise post_Booking und put_Booking belegt. Sie stehen für Anlage und Änderung in den entsprechenden Buchungsabläufen. Aus einem bestimmten fachlichen Status wie «bezahlt» darf kein frei erfundener Topicname abgeleitet werden. Prüfen Sie das tatsächlich benötigte Geschäftsereignis mit einer passenden Demobuchung.

Lesen Sie die Konfiguration über GET /v2/webhook/{id} zurück und vergleichen Sie URL, Status und gespeicherte Topics. Unbekannte oder fehlerhaft geschriebene Einträge können beim Speichern unberücksichtigt bleiben; eine erfolgreiche Antwort allein bestätigt nicht, dass jeder gewünschte Name übernommen wurde.

Beim Aktualisieren der topics-Liste wird die vollständige gewünschte Liste gesetzt. Eine leere Liste entfernt die gespeicherten Topics. Senden Sie deshalb auch weiterhin benötigte Ereignisnamen mit.

Empfang und Signatur am unveränderten Body prüfen

edoobox sendet einen HTTP-POST mit JSON. Der Header edhook identifiziert den konkreten Versand. Bei hinterlegtem Secret enthält edsignature eine hexadezimale HMAC-SHA256-Signatur des gesendeten JSON-Bodys. Berechnen Sie den Vergleich aus den unveränderten empfangenen Bytes. JSON zuerst einzulesen und neu zu serialisieren kann Reihenfolge oder Zeichenkodierung verändern.

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

function validEdooboxSignature(rawBody, signature, secret) {
  if (typeof signature !== 'string' || !/^[0-9a-f]{64}$/i.test(signature)) {
    return false;
  }
  const expected = createHmac('sha256', secret).update(rawBody).digest();
  const received = Buffer.from(signature, 'hex');
  return expected.length === received.length && timingSafeEqual(expected, received);
}
// rawBody vor einem JSON-Parser als unveränderten Buffer sichern.
// secret aus dem serverseitigen Secret-Speicher lesen.

Prüfen Sie erst die Signatur und die Zuordnung zur eingerichteten Verbindung. Verarbeiten Sie danach den JSON-Inhalt. Dieser besitzt einen Bereich hook mit unter anderem topic, time, method, account und webhook sowie einen Bereich data. Die Datenform hängt vom Ereignis und dessen Erzeugungsweg ab; eine Erweiterung kann zusätzliche Daten enthalten.

Der Kontextwert hook.edid ist kein API-Zugriffstoken. Für einen anschliessenden REST-Abruf verwenden Sie weiterhin Ihre eigene erfolgreiche API-Authentifizierung und deren Konto-Kontext.

Aktivieren und den gesamten Ablauf prüfen

Lesen Sie die vorbereitete Konfiguration zurück und kontrollieren Sie Empfänger, Secret-Konfiguration und Topics.
Aktivieren Sie sie mit PUT /v2/webhook/{id} und dem Body {"data":{"status":true}}.
Lösen Sie in einem vereinbarten Demoablauf eine passende neue Buchung beziehungsweise Buchungsänderung aus.
Prüfen Sie beim Empfänger den tatsächlichen HTTP-POST, Topic, Signatur, Datenform und Buchungs-ID.
Laden Sie die betroffene Ressource mit Ihrem eigenen API-Zugang nach und kontrollieren Sie die Aktualisierung im Zielsystem.
Prüfen Sie auch eine erneute Verarbeitung derselben Buchung und einen vorübergehend nicht verfügbaren Empfänger.

Der Sender wartet nur kurz auf die Empfangsantwort. Speichern Sie ein geprüftes Ereignis deshalb zuerst dauerhaft in Ihrer eigenen Warteschlange und antworten Sie zügig mit HTTP 200. Längere CRM-Aufgaben verarbeitet Ihr Hintergrunddienst anschliessend. Eine Empfangsbestätigung sollte erst erfolgen, wenn Ihr System die angenommene Arbeit zuverlässig wieder aufnehmen kann.

Mehrfache Ereignisse und fehlende Zustellung abfangen

Verwenden Sie edhook, Topic und Ressourcen-ID für Ihre nachvollziehbare Verarbeitung. Verhindern Sie eine doppelte Buchung oder CRM-Aktion auch dann, wenn dieselbe Ressourcenänderung über unterschiedliche Wege ankommt. Der Verarbeitungsstand Ihres Zielsystems gehört in dessen dauerhafte Datenhaltung.

Planen Sie weder eine genau einmalige Zustellung noch eine feste Reihenfolge oder zugesicherte Wiederholungsintervalle ein. Prüfen Sie das tatsächliche Empfangsprotokoll und vergleichen Sie den aktuellen edoobox-Datensatz. Der ergänzende REST-Abgleich der Buchungen behandelt spätere Stornos, Deduplizierung und den erst nach vollständigem Lauf abgeschlossenen Verarbeitungsstand.

Bei ausbleibenden Nachrichten prüfen Sie Aktivstatus, gespeicherte Topics, tatsächlich ausgeführte Aktion, Empfangsadresse, Firewall, Signaturprüfung und Empfängerprotokoll. Ein API-GET auf eine Buchung erzeugt selbst kein Anlage- oder Änderungsereignis. Starten Sie zur Fehlersuche keine echten mehrfachen Buchungen.

Adresse, Secret oder Betrieb kontrolliert ändern

Deaktivieren Sie die Konfiguration bei Bedarf mit PUT /v2/webhook/{id} und {"data":{"status":false}}. Lesen Sie den Status danach zurück. Bereits vom Empfänger angenommene Arbeit wird durch dieses Deaktivieren nicht aus dessen Warteschlange entfernt.

Ändern Sie URL, Secret und Topics mit derselben ID. Stimmen Sie einen Secret-Wechsel zwischen Senderkonfiguration und Empfänger ab und prüfen Sie vor dem erneuten Aktivieren die Signatur. Wenn ein Eintrag endgültig entfallen soll, unterstützt DELETE /v2/webhook/{id} das Entfernen. Prüfen Sie vorher Abhängigkeiten und behalten Sie den REST-Abgleich als kontrollierten Übergang bei.

Beispiel: Buchungsänderung im CRM übernehmen

Eine Organisation betreibt einen eigenen Empfänger für Buchungen. Nach einer gültigen Signatur speichert dieser die Nachricht und bestätigt den Empfang. Der Hintergrunddienst ermittelt die betroffene Buchung, liest ihren aktuellen edoobox-Stand und aktualisiert die bereits gespeicherte CRM-Zuordnung. Ein erneutes Ereignis derselben Buchung aktualisiert denselben Datensatz.

Ein regelmässiger REST-Lauf gleicht zusätzlich den relevanten Buchungsbestand ab. So bleibt eine vorübergehende Empfangsstörung bearbeitbar. Das Beispiel setzt eine eigene Integration voraus; das Anlegen eines Webhooks erstellt noch keinen fertigen CRM-Abgleich.