Webhooks

Webhooks für Integration mit externen Systemen

Neben der API, mit der bspw. die Liste der bevorstehenden Veranstaltungstermine abgefragt oder Buchungen angelegt werden können, bietet SeminarDesk mit der Webhook-Funktionalität eine weitere Integrationsmöglichkeit an.

Webhooks erlauben es, automatisiert Benachrichtigungen von SeminarDesk beim Eintreten bestimmter Ereignisse an ein beliebiges externes System zu senden, welches diese Information dann auswerten und weiterverarbeiten kann. Dabei könnte es sich zum Beispiel um ein CMS wie WordPress handeln. (Tatsächlich nutzt das SeminarDesk Plugin für WordPress die hier beschriebenen Webhooks.) Zum allgemeinen Konzept von Webhooks sei bspw. dieser Grundlagen-Artikel empfohlen.

Konfiguration von Webhooks in SeminarDesk

Webhooks werden unter Verwaltung – Setup – Webhooks und Schnittstellen angelegt.

Dabei sind folgende Angaben nötig:

• Webhook URL: Dies ist die sog. Endpoint URL, an welche die Events geschickt werden sollen. Es muss sich um eine valide, vollständige und öffentlich erreichbare HTTPS-URL handeln.
• Authentifizierung: Derzeit wird HTTP-Basic-Auth unter der Angabe von Benutzername und Passwort verwendet.
• Angabe der Ereignisse, bei denen der Webhook benachrichtigt werden soll. Dafür gibt es zurzeit folgende Möglichkeiten:
  1. event.create – Wird aufgerufen, wenn eine Veranstaltung das erste Mal in den Buchungsseite-Status „Veröffentlicht“ versetzt wird.
  2. event.update – Wird aufgerufen, wenn eine Veranstaltung geändert wird.
  3. event.delete – Wird aufgerufen, wenn eine Veranstaltung in einen Status versetzt wird, der als „Ist storniert“ markiert ist.
  4. eventDate.create – Veranstaltungstermin wurde angelegt bzw. veröffentlicht.
  5. eventDate.update – Veranstaltungstermin wurde geändert.
  6. eventDate.delete – Veranstaltungstermin wurde in einen Status versetzt, der als „Ist storniert“ markiert ist.
  7. facilitator.create – Referent*in wurde angelegt, bzw. Personen-Profil wurde als Referent*innen-Profil markiert.
  8. facilitator.update – Angaben des/r Referent*in (Name, Beschreibung, Foto) wurden geändert.
  9. facilitator.delete – Personen-Profil wurde gelöscht bzw. Referent*innen-Status wurde entfernt.
  10. labelGroup.create – Label-Gruppe wurde angelegt.
  11. labelGroup.update – Label-Gruppe bzw. ein enthaltenes Label wurde geändert.
  12. labelGroup.delete – Label-Gruppe wurde gelöscht.
  13. profile.create – Ein Profil wurde angelegt.
  14. profile.update – Ein Profil wurde geändert.
  15. profile.delete – Ein Profil wurde gelöscht.
  16. profile.merge – Zwei Profile wurden zusammengeführt.
  17. booking.create – Eine Buchung wurde angelegt.
  18. booking.statusChange – Der Status einer Buchung wurde geändert.
  19. booking.delete – Eine Buchung wurde gelöscht.
• Erweiterten Inhalt senden: Sendet die komplette Payload des Objekts, auf das sich die Aktion bezieht, also bspw. eine Veranstaltung oder ein Termin, siehe unten. Standardmäßig enthält die Payload lediglich die ID des Objekts, mit der über die API mehr Information abgefragt werden kann.

Webhook-Format

Es wird ein HTTP-Request-Body im JSON-Format an die Webhooks verschickt; hier ein Beispiel für die Aktion „event.create“:

{
    "id": "3b27fe327ae240bf838a3fb6693e9feb",
    "properties": [
       "timestamp": 1583509807000,
    ],
    "notifications": [{ 
       "action": "event.create",
       "payload": {         
          // ...     
       }
    }]
}

• id: Eindeutige ID (UUID) des Requests
• properties.timestamp: Zeitstempel des Requests
• notifications: Liste der Ereignisse
  • action: Ereignis, s. Liste oben
  • payload: Das Objekt, auf das sich die Aktion bezieht, also bspw. eine Veranstaltung oder ein Termin. Die vollständige Dokumentation der Payloads findet sich hier.