Der Webhook kann verwendet werden um externe Systeme, wie zum Beispiel Salesforce, oder auch andere CRM Systeme anzubinden. Eventuell ist es nötig, eine Middleware (Zapier o.ä.) dazwischen zu schalten.
Einrichtung
Zur Einrichtung sind zwei Schritte nötig:
1. In den Einstellungen im twingleManager muss die URL des Webhhoks hinterlegt werden. Diese Oberfläche ist im Reiter Allgemein zu finden.
- Die URL des Webhhoks muss angegeben werden
- Optional kann ein Secret zur späteren Verifizierung verwendet werden
- Optional kann eine Verzögerung bei der Übermittlung von neuen Transaktionen eingestellt werden. Dies kann zum Beispiel hilfreich sein um sicher zu gehen, dass genug Zeit dass die Unterstützer*innen nach der Spende genug Zeit hatten Ihre Daten zu hinterlegen.
2. In den Projekteinstellungen muss für jedes Projekt von dem aus Daten übertragen werden sollen der Webhook aktiviert werden.
Bitte beachten Sie folgende Hinweise:
- von Projekten die nicht aktiviert worden sind, werden keine Daten an den Webhook übertragen
- Historische Daten, also Transkationen die zeitlich vor der Aktivierung liegen, werden nicht übertragen
Nutzung
Die Daten einer Transaktion werden immer direkt im Anschluss (oder nach gewählter Verzögerung) übertragen. Der Umfang und die Struktur der Daten ist in einem extra Artikel beschrieben. Die Daten werden im JSON-Format im body eines POST-Requests übertragen.
Der Datenumfang ist bei einer neuen Transaktion der Gleiche wie bei einer geänderten Transaktion. Ob es sich um ein Update handelt, ist im Header des Requests zu sehen. Dort wird der Wert X-Twingle-Isupdate auf 1 gesetzt, wenn es ein Update ist, sonst ist der Wert immer 0.
Sollten in der Konfiguration ein Secret hinterlegt werden, dann wird dieses benutzt um für die gesamte Payload des Request einen Hashwert zu erzeugen und diesem im Header im Feld X-Hub-Signature-256 zu übertragen. Der Hashwert ist ein sha256-Hash.