Webhooks

Übersicht

Webhooks ermöglichen es Apps mit benutzerdefinierter Integration, Events in Workplace zu abonnieren und Updates in Echtzeit zu erhalten. Wenn eine Änderung in Workplace auftritt, wird für jede App mit benutzerdefinierter Integration, die das entsprechende Webhook-Thema abonniert hat, eine HTTPS POST-Anfrage an eine Rückruf-URL gesendet.

Dadurch werden Apps effizienter, da sie genau ermitteln können, wann eine Änderung vorgenommen wird, und nicht auf fortlaufende oder sogar periodische Graph API-Anfragen angewiesen sind, um die neuesten Inhalte abzurufen.

Der Support von Webhooks für Workplace wird vom selben Framework bereitgestellt wie Webhooks für die Graph API.

Webhook-Themen abonnieren

Der Dialog Benutzerdefinierte Integration bearbeiten verfügt über Tabs zu jedem für Apps auf Workplace verfügbaren Webhook-Thema.

Den Abschnitt „Webhooks“ im Dialog „Benutzerdefinierte Integration bearbeiten“

Stelle eine Rückruf-URL und ein Verifizierungs-Token bereit, um ein neues Webhook-Abonnement zu einem vorhandenen Thema hinzuzufügen. Wähle dann die Abonnementfelder aus, die für die von deiner App bereitgestellte Funktion erforderlich sind.

Verifizierungsanfragen verarbeiten

Wenn du ein neues Abonnement hinzufügst oder ein vorhandenes bearbeitest, führen Meta-Server eine GET-Anfrage an deine Rückruf-URL aus, um die Gültigkeit des Rückrufservers zu überprüfen.

Ein Abfrage-String mit folgenden Parametern wird an diese URL angehängt:

• hub.mode – Der String „subscribe“ wird in diesem Parameter übergeben.
• hub.challenge – Ein zufälliger String.
• hub.verify_token – Der verify_token-Wert, den du beim Erstellen des Abonnements angegeben hast.

Jedes Mal, wenn dein Endpunkt eine Verifizierungsanfrage erhält, muss er folgende Schritte ausführen:

• Stelle sicher, dass der hub.verify_token-Wert mit dem String übereinstimmt, der im Feld „Verifizierungs-Token“ angegeben ist, wenn du den Webhook konfigurierst.
• Eine Antwort mit dem hub.challenge-Wert senden.

Webhook-Sicherheit

Alle Webhook-Anrufe an von Entwickler*innen definierte Rückruf-URLs erfolgen über HTTPS, wodurch die Sicherheit von Webhook-Payloads auf Transportebene gewährleistet wird.

Um zusätzliche Sicherheit zu bieten, wird ein HTTP-Header X-Hub-Signature-256 zu jeder POST-Payload hinzugefügt, den du verwenden solltest, um sicherzustellen, dass die Payload von einem Meta-Server stammt.

Umfassende Informationen zu diesem Verhalten findest du in der Dokumentation zum Webhook Framework.

Alle Webhook-Anrufe an von Entwickler*innen definierte Rückruf-URLs erfolgen über HTTPS, wodurch die Sicherheit von Webhook-Payloads auf Transportebene gewährleistet wird.

Abonnieren von Webhooks mittels eines API-Aurufs

API-Aufrufe zum Lesen oder Ändern von Webhook-Abonnements müssen über ein App-Token erfolgen anstelle des üblichen Tokens der benutzerdefinierten Integration. Ein App-Token kann durch die Verkettung der App-ID, eines „|“-Symbols und des App-Geheimcodes generiert werden.

Beispiel:

Aktuelle Webhook-Abonnements abrufen (über App-Token)

GET graph.facebook.com
  /{app-id}/subscriptions
    &access_token={your_app_token}

Neues Webhook-Abonnement hinzufügen (über App-Token)

POST graph.facebook.com
  /{app-id}/subscriptions
    ?object=page
    &fields=mention,messages
    &callback_url={your-url}
    &verify_token={your-verify-token}
    &access_token={your_app_token}

Fehlerbehebung für Seiten/App-Abonnements

Wenn Webhooks nicht wie erwartet erhalten werden, solltest du überprüfen, ob das Abonnement zwischen der Seite und der App korrekt eingerichtet ist. Diese Einrichtung erfolgt in der Regel automatisch. Sie kann jedoch fehlschlagen. Wenn beispielsweise die Auslieferung eines Webhooks über einen längeren Zeitraum nicht möglich ist, kann das Abonnement entfernt werden. Bei Apps von Drittanbietern erscheint dann eine Warnung im App-Dashboard.

Um dieses Abonnement zu überprüfen, sind folgende API-Aufrufe verfügbar:

Aktuelles Seiten/App-Abonnement abrufen (über App-Token)

GET graph.facebook.com
  /me/subscribed_apps?access_token={your_page_token}

Um dieses Abonnement neu zu erstellen, sind folgende API-Aufrufe verfügbar:

Aktuelles Seiten/App-Abonnement neu erstellen (über App-Token)

POST graph.facebook.com
  /me/subscribed_apps?access_token={your_page_token}
	{"subscribed_fields": ["messages"...]}

Webhook-Themen

Aktivitäten in Workplace werden in Themen gruppiert. Jedes Thema verfügt über eine Reihe von Feldern, die eine Verknüpfung zu Events zu einem bestimmten Thema herstellen. Apps können Webhook-Updates zu jedem Thema und für bestimmte Felder innerhalb eines Themas abonnieren.

Workplace stellt derzeit Webhooks für folgende Themen und Gruppen bereit:

Seite

Weitere Informationen findest du in den Referenzdokumenten zu Seitenthemen.

Gruppen

Weitere Informationen findest du in den Referenzdokumenten zu Gruppenthemen.

Nutzer*in

Weitere Informationen findest du in den Referenzdokumenten zu Nutzer*innen-Themen.

Sicherheit

Weitere Informationen findest du in den Referenzdokumenten zu Sicherheitsthemen.

admin_activity

Events, die ausgelöst werden, wenn ein*e Administrator*in zu einer Workplace-Community hinzugefügt oder daraus entfernt wird.

compromised_credentials

Events, die ausgelöst werden, wenn der Verdacht besteht, dass die Workplace-Passwörter einiger Konten in einer Community möglicherweise gefährdet sind.

files

Events, die bei Dateiaktivitäten in Workplace ausgelöst werden.

groups

Events, die ausgelöst werden, wenn ein*e Nutzer*in eine unternehmensübergreifende Gruppe (MCG) in Workplace erstellt oder einer solchen beitritt.

integrations

Events, die ausgelöst werden, wenn ein Administrator Eigenschaften einer Integration erstellt oder ändert.

invites

Events, die ausgelöst werden, wenn ein*e Nutzer*in Workplace beitritt, indem er*sie sich selbst einlädt.

passwords

Events, die ausgelöst werden, wenn ein*e Nutzer*in sein*ihr Passwort ändert oder das Zurücksetzen des Passworts anfordert.

sessions

Events, die ausgelöst werden, wenn sich ein*e Nutzer*in in Workplace ein- oder ausloggt.

two_factor

Events, die ausgelöst werden, wenn ein*e Nutzer*in die zweistufige Authentifizierung aktiviert oder deaktiviert.

reseller_events

Events in Bezug auf Reseller.

Links

Weitere Informationen findest du in den Referenzdokumenten zu Verknüpfungsthemen.

Wissensdatenbank

Weitere Informationen findest du in der Wissensdatenbank unter der Kategorie Graph API-Dokumentation.