Los geht’s

In diesem Dokument erfährst du, wie du einen Webhook einrichtest, der dich benachrichtigt, wenn die Nutzer deiner App ihre Nutzerfotos ändern. Wenn du einmal verstanden hast, wie du diesen Webhook einrichtest, kannst du dies auf alle Webhooks übertragen.

Für die Einrichtung von Webhooks musst du folgendermaßen vorgehen:

Erstelle einen Endpunkt auf einem sicheren Server, der HTTP-Anfragen verarbeiten kann.
Konfiguriere das Webhooks-Produkt im App-Dashboard deiner App.

Diese Schritte werden nachfolgend ausführlich erläutert.

Erstellen eines Endpunkts

Dein Endpunkt muss zwei Arten von HTTPS-Anfragen verarbeiten können: Verifizierungsanfragen und Event-Benachrichtigungen. Da beide Anfragen HTTPS verwenden, muss dein Server über ein korrekt konfiguriertes und installiertes TLS- oder SSL-Zertifikat verfügen. Selbstsignierte Zertifikate werden nicht unterstützt.

In den Abschnitten unten wird erläutert, was die einzelnen Anfragetypen enthalten und wie darauf zu reagieren ist. Alternativ kannst du unsere Beispiel-App verwenden, die bereits für die Verarbeitung dieser Anfragen konfiguriert ist.

Verifizierungsanfragen

Jedes Mal, wenn du das Webhooks-Produkt im App-Dashboard konfigurierst, senden wir eine GET-Anfrage an deine Endpunkt-URL. Verifizierungsanfragen enthalten die folgenden Abfrage-String-Parameter, die an das Ende deiner Endpunkt-URL angehängt werden. Sie sehen in etwa wie folgt aus:

Beispiel-Verifizierungsanfrage

GET https://www.your-clever-domain-name.com/webhooks? hub.mode=subscribe& hub.challenge=1158201444& hub.verify_token=meatyhamhock

Parameter	Beispielwert	Beschreibung
`hub.mode`	`subscribe`	Dieser Wert muss immer auf `subscribe` festgelegt sein.
`hub.challenge`	`1158201444`	Ein `int`, den du an uns zurückgeben musst.
`hub.verify_token`	`meatyhamhock`	Ein String, den wir aus dem Feld Bestätigungsschlüssel im App-Dashboard deiner App beziehen. Diesen String legst du fest, wenn du die Schritte unter den Webhooks-Konfigurationseinstellungen durchführst.

Hinweis:PHP konvertiert Punkte (.) in Parameternamen in Unterstriche (_).

Validierung von Verifizierungsanfragen

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

Verifizieren, dass der hub.verify_token-Wert mit dem String übereinstimmt, den du bei der Konfiguration des Webhooks-Produkts in deinem App-Dashboard im Feld Bestätigungsschlüssel festgelegt hast (du hast diesen Schlüssel-String noch nicht festgelegt).
Senden einer Antwort mit dem hub.challenge-Wert.

Wenn du dein App-Dashboard aufgerufen hast und dein Webhooks-Produkt konfigurierst (und somit eine Verifizierungsanfrage auslöst), wird im Dashboard angezeigt, ob dein Endpunkt die Anfrage richtig validiert hat. Wenn du zur Konfiguration des Webhooks-Produkts den /app/subscriptions-Endpunkt der Graph API verwendest, sendet die API eine Antwort mit einer Erfolgs- oder Fehlerangabe.

Event-Benachrichtigungen

Wenn du dein Webhooks-Produkt konfigurierst, abonnierst du bestimmte fields für einen object-Typ (z. B. das photos-Feld für das user-Objekt). Wird eines dieser Felder geändert, senden wir eine POST-Anfrage mit einer JSON-Payload an deinen Endpunkt, die die Änderung beschreibt.

Hast du beispielsweise das photos-Feld des user-Objekts abonniert und hat einer deiner App-Nutzer ein Foto veröffentlicht, senden wir dir eine POST-Anfrage ähnlich der Folgenden:

POST / HTTPS/1.1 Host: your-clever-domain-name.com/webhooks Content-Type: application/json X-Hub-Signature-256: sha256={super-long-SHA256-signature} Content-Length: 311 { "entry": [ { "time": 1520383571, "changes": [ { "field": "photos", "value": { "verb": "update", "object_id": "10211885744794461" } } ], "id": "10210299214172187", "uid": "10210299214172187" } ], "object": "user" }

Payload-Inhalt

Payloads enthalten ein Objekt mit einer Beschreibung der Änderung. Wenn du das Webhooks-Produkt konfigurierst, kannst du angeben, ob Payloads nur die Namen der geänderten Felder oder auch die neuen Werte enthalten sollen.

Wir formatieren alle Payloads mit JSON, damit du die Payload mit den gängigen JSON-Parsing-Methoden oder Paketen parsen kannst.

Wir speichern keine Webhook-Event-Benachrichtigungsdaten, die wir dir senden. Stelle also sicher, dass du den gesamten Payload-Inhalt, den du beibehalten möchtest, erfasst und speicherst.

Die meisten Payloads enthalten die folgenden gängigen Eigenschaften, aber der Inhalt und die Struktur der einzelnen Payloads ist je nachdem, welche Objektfelder du abonniert hast, unterschiedlich. In den Referenzdokumenten der einzelnen Objekte findest du die enthaltenen Felder.

Eigenschaft	Beschreibung	Typ
`object`	Der Objekttyp (z. B. `user`, `page` usw.)	`string`
`entry`	Ein Array mit einem Objekt mit einer Beschreibung der Veränderungen. Mehrere Änderungen aus unterschiedlichen Objekten desselben Typs werden in einem Batch zusammengefasst.	`array`
`id`	Die Objekt-ID	`string`
`changed_fields`	Ein String-Array mit den Namen der geänderten Felder. Wird nur berücksichtigt, wenn du die Einstellung Werte hinzufügen beim Konfigurieren des Webhooks-Produkts im App-Dashboard deiner App deaktivierst.	`array`
`changes`	Ein Array mit einem Objekt, das eine Beschreibung der geänderten Felder und ihre neuen Werte enthält. Wird nur berücksichtigt, wenn du die Einstellung Werte hinzufügen beim Konfigurieren des Webhooks-Produkts im App-Dashboard deiner App aktivierst.	`array`
`time`	Ein UNIX-Zeitstempel gibt an, wann die Event-Benachrichtigung gesendet wurde (nicht den Zeitpunkt der Änderung, die die Benachrichtigung ausgelöst hat).	`int`

Validierung der Payloads

Wir signieren alle Event-Benachrichtigungen mit einer SHA256-Signatur und nehmen die Signatur in den X-Hub-Signature-256-Header der Anfrage auf. Dabei wird sha256= vorangestellt. Du musst die Payload nicht validieren, aber wir empfehlen es dir.

So validierst du die Payload:

Generiere eine SHA256-Signatur mit der Payload und dem App-Geheimcode deiner App.
Vergleiche deine Signatur mit der Signatur im X-Hub-Signature-256-Header (alles nach sha256=). Stimmen die Signaturen überein, ist die Payload echt.

Antworten auf Event-Benachrichtigungen

Dein Endpunkt sollte auf alle Event-Benachrichtigungen mit 200 OK HTTPS antworten.

Frequenz

Event-Benachrichtigungen werden zusammengefasst und in Batches von maximal 1.000 Updates gesendet. Die Zusammenfassung in Batches kann jedoch nicht garantiert werden, also passe deine Server so an, dass sie jeden Webhook einzeln verarbeiten.

Wenn die Übertragung eines gesendeten Updates an deinen Server fehlschlägt, wiederholen wir den Vorgang unmittelbar und nehmen anschließend in immer größeren Abständen innerhalb der nächsten 36 Stunden weitere Wiederholungsversuche vor. Dein Server sollte die Deduplizierung in diesen Fällen verarbeiten können. Antworten, die nicht innerhalb von 36 Stunden bestätigt werden, werden gelöscht.

Hinweis: Die Häufigkeit, mit der Event-Benachrichtigungen von Messenger versendet werden, unterscheidet sich. Weitere Informationen findest du in der Dokumentation zu Webhooks der Messenger-Plattform.

Konfiguration des Webhooks-Produkts

Wenn dein Endpunkt oder deine Beispiel-App bereit ist, füge mithilfe des App-Dashboards deiner App das Webhooks-Produkt hinzu und konfiguriere es. Du kannst das mit dem /{app-id}/subscriptions-Endpunkt auch programmgesteuert für alle Webhooks ausgenommen Instagram durchführen.

In diesem Beispiel konfigurieren wir mit dem Dashboard einen Webhook, der alle Veränderungen von Fotos der Nutzer deiner App abonniert.

Gehe im App-Dashboard zu Produkte > Webhooks, wähle aus dem Dropdown-Menü Nutzer aus und klicke auf Dieses Objekt abonnieren.
Wahl des Nutzerobjekts
Gib die URL deines Endpunkts im Feld Rückruf-URL ein und gib im Feld Token bestätigen einen String ein. Der String wird zu allen Verifizierungsanfragen hinzugefügt. Wenn du eine unserer Beispiel-Apps verwendest, sollte es derselbe String sein, den du für die TOKEN-Konfigurationsvariable deiner App verwendet hast.
Wenn Event-Benachrichtigungs-Payloads die Namen der Felder enthalten sollen, die sich geändert haben, sowie die neuen Werte, dann stelle für den Schalter Werte hinzufügen die Option Ja ein.
Eingabe einer Endpunkt-URL und eines Bestätigungsschlüssel-Strings
Wenn du auf Bestätigen und speichern klickst, senden wir deinem Endpunkt eine Verifizierungsanfrage, die du bestätigen musst. Bestätigt dein Endpunkt die Anfrage erfolgreich, solltest du Folgendes sehen:
Erfolgreiche Validierung.
Der letzte Schritt ist das Abonnement einzelner Felder. Abonniere das photos-Feld und sende eine Test-Event-Benachrichtigung.
Abonnement des Foto-Felds im Nutzerobjekt
Ist dein Endpunkt richtig eingerichtet, sollte er die Payload validieren und den Code ausführen, für den du bei erfolgreicher Validierung festgelegt hast. Wenn du unsere Beispiel-App nutzt, lade die URL der App in deinen Web-Browser. Der Inhalt der Payload sollte angezeigt werden:
Beispiel-App mit der Anzeige der Test-Benachrichtigungs-Payload.

Nächste Schritte

Nachdem du nun gesehen hast, wie Webhooks eingerichtet werden, interessierst du dich vielleicht für unsere zusätzlichen Dokumente mit Beschreibungen von zusätzlichen Schritten für die Einrichtung von Webhooks für bestimmte Produkte: