Erste Schritte

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.

Create an Endpoint

Your endpoint must be able to process two types of HTTPS requests: Verification Requests and Event Notifications. Since both requests use HTTPs, your server must have a valid TLS or SSL certificate correctly configured and installed. Self-signed certificates are not supported.

The sections below explain what will be in each type of request and how to respond to them. Alternatively, you can use our sample app which is already configured to process these requests.

Verification Requests

Anytime you configure the Webhooks product in your App Dashboard, we'll send a GET request to your endpoint URL. Verification requests include the following query string parameters, appended to the end of your endpoint URL. They will look something like this:

Sample Verification Request

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

Parameter	Sample Value	Description
`hub.mode`	`subscribe`	This value will always be set to `subscribe`.
`hub.challenge`	`1158201444`	An `int` you must pass back to us.
`hub.verify_token`	`meatyhamhock`	A string that that we grab from the Verify Token field in your app's App Dashboard. You will set this string when you complete the Webhooks configuration settings steps.

Note: PHP converts periods (.) to underscores (_) in parameter names.

Validating Verification Requests

Whenever your endpoint receives a verification request, it must:

Verify that the hub.verify_token value matches the string you set in the Verify Token field when you configure the Webhooks product in your App Dashboard (you haven't set up this token string yet).
Respond with the hub.challenge value.

If you are in your App Dashboard and configuring your Webhooks product (and thus, triggering a Verification Request), the dashboard will indicate if your endpoint validated the request correctly. If you are using the Graph API's /app/subscriptions endpoint to configure the Webhooks product, the API will indicate success or failure with a response.

Event Notifications

When you configure your Webhooks product, you will subscribe to specific fields on an object type (e.g., the photos field on the user object). Whenever there's a change to one of these fields, we will send your endpoint a POST request with a JSON payload describing the change.

For example, if you subscribed to the user object's photos field and one of your app's Users posted a Photo, we would send you a POST request that would look something like this:

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 Contents

Payloads will contain an object describing the change. When you configure the webhooks product, you can indicate if payloads should only contain the names of changed fields, or if payloads should include the new values as well.

We format all payloads with JSON, so you can parse the payload using common JSON parsing methods or packages.

We do not store any Webhook event notification data that we send you, so be sure to capture and store any payload content that you want to keep.

Most payloads will contain the following common properties, but the contents and structure of each payload varies depending on the object fields you are subscribed to. Refer to each object's reference document to see which fields will be included.

Property	Description	Type
`object`	The object's type (e.g., `user`, `page`, etc.)	`string`
`entry`	An array containing an object describing the changes. Multiple changes from different objects that are of the same type may be batched together.	`array`
`id`	The object's ID	`string`
`changed_fields`	An array of strings indicating the names of the fields that have been changed. Only included if you disable the Include Values setting when configuring the Webhooks product in your app's App Dashboard.	`array`
`changes`	An array containing an object describing the changed fields and their new values. Only included if you enable the Include Values setting when configuring the Webhooks product in your app's App Dashboard.	`array`
`time`	A UNIX timestamp indicating when the Event Notification was sent (not when the change that triggered the notification occurred).	`int`

Validating Payloads

We sign all Event Notification payloads with a SHA256 signature and include the signature in the request's X-Hub-Signature-256 header, preceded with sha256=. You don't have to validate the payload, but you should.

To validate the payload:

Generate a SHA256 signature using the payload and your app's App Secret.
Compare your signature to the signature in the X-Hub-Signature-256 header (everything after sha256=). If the signatures match, the payload is genuine.

Responding to Event Notifications

Your endpoint should respond to all Event Notifications with 200 OK HTTPS.

Frequency

Event Notifications are aggregated and sent in a batch with a maximum of 1000 updates. However batching cannot be guaranteed so be sure to adjust your servers to handle each Webhook individually.

If any update sent to your server fails, we will retry immediately, then try a few more times with decreasing frequency over the next 36 hours. Your server should handle deduplication in these cases. Unacknowledged responses will be dropped after 36 hours.

Note: The frequency with which Messenger event notifications are sent is different. Please refer to the Messenger Platform Webhooks documentation for more information.

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 Nutzer*innenobjekts
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 Nutzer*innenobjekt
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.

mTLS für Webhooks

Mutual TLS (mTLS) ist eine Methode zur gegenseitigen Authentifizierung.

mTLS stellt sicher, dass die Parteien an beiden Enden einer Netzwerkverbindung die sind, die sie behaupten zu sein, indem überprüft wird, ob sie beide den richtigen privaten Schlüssel besitzen. Die Informationen in den jeweiligen TLS-Zertifikaten ermöglichen eine zusätzliche Verifizierung.

Konfigurieren von mTLS

Sobald du mTLS für dein WhatsApp-Unternehmenskonto-Abonnement aktivierst, präsentiert Meta ein Clientzertifikat zusammen mit dem zugehörigen signierenden Zwischenzertifikat. Beide Zertifikate werden zum Erstellen eines TLS-Handshake von Webhook-Anfragen an deinen Server verwendet. Dein Server kann dann die Identität des Absenders dieser Anfragen anhand der Vertrauenskette und des Common Name (CN) verifizieren.

Das Clientzertifikat wird von einem CA-Zwischenzertifikat, DigiCert SHA2 High Assurance Server CA, und anschließend von einem Root-CA-Zertifikat, DigiCert High Assurance EV Root CA, signiert. Beachte, dass das Zwischenzertifikat auch das Zertifikat für graph.facebook.com signiert:

Verifizierung des Clientzertifikats

Nachdem du HTTPS für den Empfang von Webhook-Anfragen eingerichtet hast, führe die folgenden Schritte aus, um das Clientzertifikat und seinen Common Name client.webhooks.fbclientcerts.com zu überprüfen:

Das Root-Zertifikat installieren
Das Clientzertifikat anhand des Root-Zertifikats verifizieren
Den Common Name (client.webhooks.fbclientcerts.com) des Clientzertifikats verifizieren

Hinweis: Server, die Webhooks empfangen, müssen HTTPS verwenden, und wir verifizieren aus Sicherheitsgründen immer das Zertifikat deines HTTPS-Servers.

Beispiel

Je nachdem, wie dein Server eingerichtet ist, fallen die obigen Schritte im Detail unterschiedlich aus. Wir veranschaulichen dies anhand zweier Beispiele, eines für Nginx und eines für AWS Application Load Balancer (ALB).

Nginx

Lade das Root-Zertifikat (DigiCert High Assurance EV Root CA) von DigiCert auf deinen Server herunter, z. B. /etc/ssl/certs/DigiCert_High_Assurance_EV_Root_CA.pem

Aktiviere mTLS über Nginx-Anweisungen (Beispiel-Screenshot)

ssl_verify_client       on;
ssl_client_certificate  /etc/ssl/certs/DigiCert_High_Assurance_EV_Root_CA.pem;
ssl_verify_depth        3;

Bestätige, dass der CN aus der eingebetteten Nginx-Variablen $ssl_client_s_dn"client.webhooks.fbclientcerts.com" ist (Beispiel-Screenshot)
```
if ($ssl_client_s_dn ~ "CN=client.webhooks.fbclientcerts.com") {
    return 200 "$ssl_client_s_dn";
}
```

AWS Application Load Balancer (ALB)

Lade das Zwischenzertifikat (DigiCert SHA2 High Assurance Server CA) von DigiCert in einen S3-Bucket herunter. Das Root-Zertifikat wird von AWS nicht akzeptiert, weil es mit dem Algorithmus SHA1withRSA signiert ist. Das Zwischenzertifikat hingegen ist mit SHA256withRSA signiert und wird somit akzeptiert.
Konfiguriere den HTTPS-Listener auf dem ALB, um mTLS mit dem Trust Store zu aktivieren, der das Zertifikat im S3-Bucket enthält (Beispiel-Sreenshot).
Extrahiere in deinem App-Code den CN aus dem HTTP-Header “X-Amzn-Mtls-Clientcert-Subject” und bestätige, dass dieser “client.webhooks.fbclientcerts.com” ist.

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: