Zum Hauptinhalt springen

Webhook-Integration

Überblick​

Webhooks ermöglichen es Ihrem System, automatisch über Änderungen in EDM benachrichtigt zu werden. Registrieren Sie einmal Ihre Endpunkte für bestimmte Ereignisse und erhalten Sie automatische Benachrichtigungen, sobald diese eintreten.

Funktionsweise​

  1. Sie registrieren einen Webhook-Endpunkt über die EDM-Oberfläche (Administration -> Zugriff -> Webhooks)
  2. Sie wählen aus, für welche Ereignisse (Events) Sie benachrichtigt werden möchten
  3. Bei Eintreten eines Ereignisses sendet EDM automatisch einen HTTP POST-Request an Ihre URL
  4. Ihre Anwendung verarbeitet die empfangenen Daten

Verfügbare Ereignisse​

Teilnehmer & Dozenten​

Teilnehmer (Attendee)

  • attendee.created - Neuer Teilnehmer wurde angelegt
  • attendee.updated - Teilnehmerdaten wurden geändert
  • attendee.deleted - Teilnehmer wurde gelöscht

Dozenten (Lecturer)

  • lecturer.created - Neuer Dozent wurde angelegt
  • lecturer.updated - Dozentendaten wurden geändert (inkl. Qualifikationen und Kategorien)
  • lecturer.deleted - Dozent wurde gelöscht

Kontaktinformationen

  • attendee.contact_info.created/updated/deleted - Kontaktinfo eines Teilnehmers
  • lecturer.contact_info.created/updated/deleted - Kontaktinfo eines Dozenten

Veranstaltungen​

Veranstaltung (Event)

  • event.created - Neue Veranstaltung wurde erstellt
  • event.deleted - Veranstaltung wurde gelöscht
  • event.status.update - Status einer Veranstaltung hat sich geändert

Veranstaltungstermine (EventDate)

  • eventdate.created - Neuer Termin wurde angelegt
  • eventdate.updated - Termin wurde geändert (inkl. Raumzuweisungen)
  • eventdate.deleted - Termin wurde gelöscht

Veranstaltungsvorlagen (EventBase)

  • eventbase.created - Neue Vorlage wurde erstellt
  • eventbase.updated - Vorlage wurde geändert
  • eventbase.deleted - Vorlage wurde gelöscht

Buchungen & Rechnungen​

Buchungen (Booking)

  • booking.created - Neue Buchung wurde erstellt
  • booking.status.update - Buchungsstatus hat sich geändert

Rechnungen (Invoice)

  • invoice.created - Neue Rechnung wurde erstellt
  • invoice.paid.update - Zahlungsstatus wurde geändert

Custom Fields​

Für alle Custom Field-Daten stehen folgende Events zur Verfügung:

  • attendee.custom_field.created/updated/deleted
  • lecturer.custom_field.created/updated/deleted
  • event.custom_field.created/updated/deleted
  • event_base.custom_field.created/updated/deleted
  • booking.custom_field.created/updated/deleted

Webhook-Subscription einrichten​

Erforderliche Daten​

Felder:

  • name: Beschreibender Name für die Subscription
  • endpoint_url: Ihre URL, die benachrichtigt werden soll
  • event_types: Array der Event-Typen, die Sie empfangen möchten
  • secret: Optionaler Secret-Key zur Authentifizierung
  • is_active: Aktiviert/Deaktiviert die Subscription

Webhook-Payload​

Struktur​

Jeder Webhook-Request enthält folgende Struktur:

{
  "event": "booking.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": 123
    // weitere ereignis-spezifische Daten
  }
}

Beispiele​

Bei Buchungserstellung:

{
  "event": "booking.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": 123
  }
}

Bei Statusänderung:

{
  "event": "booking.status.update",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": 123,
    "old_status": "pending",
    "new_status": "confirmed"
  }
}

Bei Rechnungszahlung:

{
  "event": "invoice.paid.update",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": 456,
    "is_paid": true
  }
}

HTTP-Header​

Mit jedem Webhook-Request werden folgende Header gesendet:

Content-Type: application/json
X-Webhook-Event: booking.created
Authorization: Bearer <ihr-secret>  // falls konfiguriert

Webhook-Empfang implementieren​

Anforderungen an Ihren Endpunkt​

  • Akzeptiert HTTP POST-Requests
  • Verarbeitet JSON-Payloads
  • Antwortet mit HTTP 2xx Status bei Erfolg
  • Reagiert innerhalb von 30 Sekunden

Fehlerbehandlung & Wiederholung​

Automatische Wiederholungen​

Wenn Ihr Endpunkt nicht erreichbar ist oder einen Fehler zurückgibt:

  • EDM wiederholt die Zustellung automatisch bis zu 5 Mal
  • Zwischen den Versuchen liegt jeweils 60 Sekunden Wartezeit
  • Der Zustellungsstatus wird protokolliert

Best Practices​

  1. Schnelle Antwort: Antworten Sie schnell mit HTTP 200 und verarbeiten Sie die Daten asynchron
  2. Idempotenz: Gestalten Sie Ihre Verarbeitung idempotent - ein Webhook könnte mehrfach empfangen werden
  3. Secret verwenden: Nutzen Sie den Secret-Parameter zur Authentifizierung

Sicherheit​

Secret-Authentifizierung​

Nutzen Sie den secret-Parameter bei der Subscription-Erstellung. EDM sendet diesen dann im Authorization-Header mit:

Authorization: Bearer ihr-geheimer-schluessel

Validieren Sie diesen Header in Ihrem Endpunkt, bevor Sie die Daten verarbeiten.

Update-Benachrichtigungen​

Bei updated-Events werden nur tatsächliche Änderungen gemeldet. Wenn ein Datensatz gespeichert wird, aber keine Felder geändert wurden, wird kein Webhook versendet.