Webhooks

Webhooks für Integration mit externen Systemen

Neben der Public API, mit der bspw. die Liste der bevorstehenden Veranstaltungstermine abgefragt oder Buchungen angelegt werden können, und der Private API, die nach etwas Konfiguration auch Zugriff auf Profile und Rechnungen ermöglicht, 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. Beispielsweise 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 sowie ö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.update – Eine Buchung wurde geändert.
  19. booking.changestatus – Der Status einer Buchung wurde geändert.
  20. booking.delete – Eine Buchung wurde gelöscht.
  21. invoice.post – Eine Rechnung wurde gebucht.
  22. invoice.cancel – Eine Rechnung wurde storniert.
  23. payment.create – Eine Zahlung für eine Buchung wurde erfasst.
  24. payment.delete – Eine Zahlung für 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.

Hinweise:

• In den Allgemeinen Einstellungen kann festgelegt werden, ob auch die Werte von Extrafeldern für Veranstaltungen/Termine und für Profile in den entsprechenden Payloads (als Teil des erweiterten Inhalts) enthalten sein sollen oder nicht.
• Je nach gebuchtem SeminarDesk-Paket, aktivierten Modulen, den Systemeinstellungen und individuellen Berechtigungen sind eventuell nicht alle hier aufgeführten Optionen verfügbar.

Webhook-Format

Es wird ein HTTP-Request-Body im JSON-Format an die Webhooks verschickt; im Folgenden 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.

Webhooks-Protokoll

Unter Verwaltung – Setup – Protokolle anzeigen – Webhooks sind alle gesendeten Webhook-Benachrichtigungen protokolliert, um die Entwicklung sowie Fehlerbehebung von Integrationen mit Webhooks zu erleichtern. Dort besteht auch die Möglichkeit, eine vergangene Nachricht erneut senden zu lassen. Diese Aktion sendet eine exakt gleiche Benachrichtigung an die URL des betroffenen Webhooks.