Introducción

En este documento se explica cómo configurar un webhook que te notificará siempre que los usuarios de la aplicación publiquen algún cambio en sus fotos de usuario. Cuando comprendas cómo configurar este webhook, sabrás configurar todos los webhooks.

Para configurar un webhook, debes realizar las acciones siguientes:

Crea un extremo en un servidor seguro que pueda procesar solicitudes HTTPS.
Configura el producto Webhooks en el panel de aplicaciones de tu aplicación.

A continuación se explican de forma detallada estos pasos.

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.

Configurar el producto Webhooks

Cuando la aplicación de ejemplo o el extremo esté listo, utiliza el panel de aplicaciones de tu aplicación para añadir y configurar el producto Webhooks. Si quieres hacerlo mediante programación, utiliza el extremo /{app-id}/subscriptions para todos los webhooks excepto el de Instagram.

En este ejemplo, usaremos el panel para configurar un webhook que se suscriba a los cambios en las fotos de cualquier usuario de la aplicación.

En el panel de aplicaciones, accede a Productos > Webhooks, selecciona Usuario en el menú desplegable y, a continuación, haz clic en Suscribirse a este objeto.
Elección del objeto de usuario.
Introduce la URL del extremo en el campo URL de devolución de llamada e introduce una cadena en el campo Identificador de verificación. Esta cadena se incluirá en todas las solicitudes de verificación. Si utilizas una de nuestras aplicaciones de ejemplo, esta cadena debe ser la misma que la utilizada para la variable de configuración TOKEN de tu aplicación.
Si quieres que las cargas útiles de las notificaciones de eventos incluyan los nombres de los campos que han cambiado, así como sus nuevos valores, establece la opción Incluir valores en Sí.
Introducción de la URL de un extremo y una cadena de identificador de verificación.
Al hacer clic en Verificar y guardar, se enviará al extremo una solicitud de verificación que debes validar. Si el extremo valida correctamente la solicitud, deberías ver lo siguiente:
Validación realizada correctamente.
El último paso consiste en suscribirse a campos individuales. Suscríbete al campo photos y envía una notificación de evento de prueba.
Suscripción al campo de fotos del objeto de usuario.
Si el extremo está configurado correctamente, debe validar la carga útil y ejecutar el código que hayas configurado para ejecutarse cuando se realice correctamente una validación. Si utilizas nuestra aplicación de ejemplo, carga la URL de la aplicación en el navegador web. Debe mostrar el contenido de la carga útil:
Aplicación de ejemplo que muestra la carga útil de una notificación de prueba.

mTLS para webhooks

El protocolo TLS mutuo (mTLS) es un método de autenticación mutua.

Para garantizar que las partes de cada extremo de la conexión de red son quienes afirman ser, mTLS verifica que ambas tengan la clave privada correcta. Además, la información de los respectivos certificados TLS proporciona una verificación adicional.

Cómo configurar mTLS

Una vez que actives mTLS en la suscripción a la cuenta de WhatsApp Business, Meta presentará un certificado de cliente junto con su certificado intermedio de firma. Ambos certificados se usan para crear un protocolo de enlace TLS de solicitudes de webhooks a tu servidor. Entonces, el servidor podrá verificar la identidad del emisor de estas solicitudes mediante la cadena de confianza y el nombre común.

El certificado de cliente lo firma un certificado de CA intermedio (DigiCert SHA2 High Assurance Server CA) y, posteriormente, un certificado de CA raíz (DigiCert High Assurance EV Root CA). Ten en cuenta que el certificado intermedio también firma el certificado de graph.facebook.com:

Verificación del certificado de cliente

Cuando hayas configurado HTTPS para recibir solicitudes de webhooks, sigue los pasos que se indican a continuación para verificar el certificado de cliente y su nombre común, client.webhooks.fbclientcerts.com:

Instalar el certificado raíz
Verificar el certificado de cliente con el certificado raíz
Verificar el nombre común (client.webhooks.fbclientcerts.com) del certificado de cliente

Nota: Los servidores que reciban webhooks deben utilizar HTTPS y, por seguridad, verificamos constantemente el certificado del servidor HTTPS.

Ejemplo

Dependiendo de la configuración del servidor, los detalles de los pasos anteriores varían. Ilustramos esto con dos ejemplos: uno para Nginx y otro para el equilibrador de carga de aplicación (ALB) de AWS.

Nginx

Descarga el certificado raíz (DigiCert High Assurance EV Root CA) de DigiCert en tu servidor; p. ej., /etc/ssl/certs/DigiCert_High_Assurance_EV_Root_CA.pem.

Activa mTLS según las directivas de Nginx (captura de pantalla de ejemplo).

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

Verifica que el nombre común de la variable incrustada de Nginx $ssl_client_s_dn coincida con "client.webhooks.fbclientcerts.com" (captura de pantalla de ejemplo).
```
if ($ssl_client_s_dn ~ "CN=client.webhooks.fbclientcerts.com") {
    return 200 "$ssl_client_s_dn";
}
```

Equilibrador de carga de aplicación (ALB) de AWS

Descarga el certificado intermedio (DigiCert SHA2 High Assurance Server CA) de DigiCert en un contenedor de S3. AWS no acepta el certificado raíz porque está firmado mediante el algoritmo SHA1withRSA; en cambio, el certificado intermedio está firmado mediante el algoritmo SHA256withRSA y, por lo tanto, se acepta.
Configura el agente de escucha HTTPS en el ALB para activar mTLS con el almacén de confianza que contiene el certificado en el contenedor de S3 (captura de pantalla de ejemplo).
En el código de la aplicación, extrae el nombre común del encabezado HTTP “X-Amzn-Mtls-Clientcert-Subject” y verifica que coincida con “client.webhooks.fbclientcerts.com”.

Siguientes pasos

Ahora que ya sabes cómo configurar Webhooks, puede que quieras consultar nuestros documentos complementarios en los que se describen los pasos adicionales involucrados al configurar Webhooks para productos específicos: