Schnittstellen: WebHooks

Webhooks bieten eine universelle und einfache Möglichkeit, bei Eintreten eines Ereignisses auf einem Server ein Ereignis auf einem anderen Server auszulösen.

Beispielsweise übergibt das MAILINGWORK-Ereignis "Newsletter-Anmeldung erfolgreich" die Anmeldedaten an eine URL Ihres Servers. Das geschieht in Form von JSON im Body des POST-Requests. Intern werden WebHooks auch von unserer Zapier-Schnittstelle verwendet.

WebHooks in Ideenfabrik Mailingwork verwalten

WebHooks lassen sich mit Hilfe des Ideenfabrik Mailingwork-Webservice (API) erstellen, anzeigen und löschen. Die Reaktivierung fehlgeschlagener WebHooks ist wahlweise per API oder per Klick innerhalb der ausgelösten Systembenachrichtigung möglich.

Zur Verwaltung von Webhooks gibt es vier API-Funktionen. Am schnellsten lernen Sie das Verhalten von API-Funktionen im Menü 'Extras ⇒ Schnittstellen ⇒ Webservicedemo' kennen. Füllen Sie die gewünschten Parameter aus und kopieren Sie den erzeugten Beispielcode in Ihr Script.

Funktion 'CreateWebHook'

Die Funktion 'CreateWebHook' verbindet ein MAILINGWORK-Ereignis mit Ihrer gewünschten Server-URL. Dazu übergeben Sie drei Parameter:

• app: beliebiger Name des Webhooks zum internen Gebrauch, auf den Sie später per 'GetWebHooks' auch filtern können
• event: Name des Ideenfabrik Mailingwork-Ereignisses, auf das Sie später per 'GetWebHooks' auch filtern können, aktuell werden folgende Ereignisse unterstützt:
  ▸ optin_finalized: Anmeldung erfolgreich
  ▸ optout_finalized: Abmeldung erfolgreich
  ▸ profilemanager_finalized: Änderung von Abonnentendaten per Profilmanager gesendet
• url: Ihre Server-URL, die die JSON-Daten entgegennimmt

Funktion 'GetWebHooks'

Die Funktion 'GetWebHooks' zeigt die Eigenschaften aller erstellten Webhooks an. Optional können Sie auf die Eigenschaften 'app' und 'event' filtern.

Funktion 'ActivateWebHook'

Die Funktion 'ActivateWebHook' aktiviert einen WebHook, der vom System automatisch deaktiviert wurde. Das ist der Fall, nachdem die URL des WebHooks wiederholt nicht erreichbar war. Bitte stellen Sie vor Aktivierung sicher, dass die URL wieder erreichbar ist.

Geben Sie den optionalen Parameter 'replayEvents=1' mit, wenn die in den ersten 5 Tagen nach Deaktivierung aufgelaufenen Events nachträglich gesendet werden sollen. Den aktuellen Aktivierungsstatus eines Webhooks liefert 'GetWebHooks' im Ergebnisparameter 'active'.

Funktion 'DeleteWebHookById'

Die Funktion 'DeleteWebHookById' löscht einen WebHook, der nicht mehr benötigt wird, oder den Sie anschließend mit geänderten Parametern neu angelegen möchten.

Fehlebehandlung, wenn URL nicht erreichbar

Schlägt der Aufruf eines WebHooks wiederholt fehl, weil die hinterlegte URL nicht erreichbar ist, wird dieser WebHook vom System automatisch deaktiviert. Parallel wird eine Systembenachrichtigung ausgelöst, über die Sie den WebHook per Klick wieder aktivieren können. Bitte stellen Sie vor Aktivierung sicher, dass die URL wieder erreichbar ist.

In den ersten 5 Tagen nach Deaktivierung speichert das Systeme eingehende Events in einem Puffer. Bei der Aktivierung können Sie entscheiden, ob diese Events nachgeholt werden sollen.