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.

Crear un extremo

El extremo debe ser capaz de procesar dos tipos de solicitudes HTTPS: solicitudes de verificación y notificaciones de eventos. Dado que ambas solicitudes usan HTTP, el servidor debe tener un certificado TLS o SSL válido configurado e instalado correctamente. Ten en cuenta que no se admiten los certificados autofirmados.

En las secciones incluidas a continuación se explica qué habrá en cada tipo de solicitud y cómo responder a ellas. Como alternativa, puedes usar nuestra aplicación de ejemplo, que ya está configurada para procesar estas solicitudes.

Solicitudes de verificación

Al configurar el producto Webhooks en el panel de aplicaciones, enviaremos una solicitud GET a la URL del extremo. En las solicitudes de verificación se incluyen los siguientes parámetros de cadena de consulta, anexados al final de la URL del extremo. El aspecto será similar al siguiente:

Ejemplo de solicitud de verificación

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

Parámetro	Valor de ejemplo	Descripción
`hub.mode`	`subscribe`	Este valor siempre se establecerá en `subscribe`.
`hub.challenge`	`1158201444`	Un valor de tipo `int` que nos debes devolver.
`hub.verify_token`	`meatyhamhock`	Una cadena que cogemos del campo Identificador de verificación del panel de aplicaciones de tu aplicación. Establecerás esta cadena al completar los pasos de configuración de Webhooks.

Nota:PHP convierte los puntos (.) en guiones bajos (_) en los nombres de parámetros.

Validar solicitudes de verificación

Cada vez que el extremo recibe una solicitud de verificación, debe realizar las acciones siguientes:

Verificar que el valor de hub.verify_token coincide con la cadena establecida en el campo Identificador de verificación al configurar el producto Webhooks en el panel de aplicaciones (esta cadena de identificador no se ha configurado todavía).
Responder con el valor de hub.challenge.

Si estás en el panel de aplicaciones configurando el producto Webhooks (y, por lo tanto, activando una solicitud de verificación), el panel indicará si el extremo ha validado correctamente la solicitud. Si usas el extremo /app/subscriptions de la API Graph para configurar el producto Webhooks, la API indicará si la operación se ha realizado correctamente o no con una respuesta.

Notificaciones de eventos

Al configurar el producto Webhooks, te suscribirás a campos (fields) específicos de un tipo de objeto (object); p. ej., el campo photos del objeto user. Cuando se produce un cambio en uno de estos campos, enviaremos una solicitud POST al extremo con una carga útil JSON que describirá el cambio.

Por ejemplo, si te has suscrito al campo photos del objeto user y un usuario de la aplicación ha publicado una foto, te enviaremos una solicitud POST que tendrá un aspecto similar al siguiente:

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" }

Contenido de la carga útil

Las cargas útiles contendrán un objeto que describirá el cambio. Al configurar el producto Webhooks, puedes indicar si las cargas útiles deben contener los nombres de los campos cambiados o si también deben incluir los nuevos valores.

Damos formato a todas las cargas útiles mediante JSON, por lo que puedes analizarlas mediante los paquetes o métodos comunes de análisis de JSON.

No almacenamos los datos de las notificaciones de eventos de webhooks que te enviamos, por lo que debes asegurarte de capturar y almacenar el contenido de las cargas útiles que quieras conservar.

La mayoría de las cargas útiles contendrán las siguientes propiedades comunes, pero el contenido y la estructura de cada carga útil varía en función de los campos del objeto a los que te hayas suscrito. Consulta el documento de referencia de cada objeto para ver qué campos se incluirán.

Propiedad	Descripción	Tipo
`object`	Tipo de objeto (p. ej., `user`, `page`, etc.).	`string`
`entry`	Matriz que contiene un objeto que describe los cambios. Es posible que se agrupen varios cambios de diferentes objetos que sean del mismo tipo.	`array`
`id`	Identificador del objeto.	`string`
`changed_fields`	Matriz de cadenas que indican los nombres de los campos que se han cambiado. Solo se incluye si desactivas la configuración Incluir valores al configurar el producto Webhooks en el panel de aplicaciones de tu aplicación.	`array`
`changes`	Matriz que contiene un objeto que describe los campos cambiados y sus nuevos valores. Solo se incluyen si activas la configuración Incluir valores al configurar el producto Webhooks en el panel de aplicaciones de tu aplicación.	`array`
`time`	Marca de tiempo UNIX que indica cuándo se envió la notificación de evento (no cuándo se produjo el cambio que activó la notificación).	`int`

Validar cargas útiles

Firmamos todas las cargas útiles de las notificaciones de eventos con una firma SHA256 e incluimos esta firma precedida de sha256= en el encabezado X-Hub-Signature-256 de la solicitud. Aunque no tienes que validar la carga útil, deberías hacerlo.

Para validar la carga útil, sigue estos pasos:

Genera una firma SHA256 mediante la carga útil y la clave secreta de la aplicación.
Compara tu firma con la del encabezado X-Hub-Signature-256 (todo lo que haya después de sha256=). Si las firmas coinciden, la carga útil es auténtica.

Responder a notificaciones de eventos

El extremo debe responder a todas las notificaciones de eventos con 200 OK HTTPS.

Frecuencia

Las notificaciones de eventos se agrupan y se envían en un lote con un máximo de 1000 notificaciones. Sin embargo, no se puede garantizar la agrupación, por lo que debes asegurarte de ajustar los servidores para que administren cada webhook de forma individual.

Si se produce un error en alguna notificación enviada al servidor, lo volveremos a intentar de inmediato y, a continuación, lo intentaremos unas veces más con una frecuencia cada vez menor durante las siguientes 36 horas. En estos casos, el servidor debe administrar la eliminación de duplicados. Las respuestas sin confirmar se anularán tras 36 horas.

Nota: La frecuencia de envío de las notificaciones de eventos de Messenger es diferente. Consulta la documentación de webhooks de la plataforma de Messenger para obtener más información.

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.

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: