Primeros pasos

En este documento, se explica cómo configurar un webhook que te notificará cuando los usuarios de tu app publiquen un cambio en sus fotos de usuario. Cuando entiendas cómo configurar este webhook, sabrás como configurar los demás.

Para configurar cualquier webhook, debes hacer lo siguiente:

Crear un punto de conexión en un servidor seguro que pueda procesar solicitudes HTTPS.
Configurar el producto Webhooks en el panel de apps de tu app.

Estos pasos se explican de manera detallada a continuación.

Creación de un punto de conexión

Tu punto de conexión debe tener la capacidad de procesar dos tipos de solicitudes HTTPS: solicitudes de verificación y notificaciones de eventos. Como ambas solicitudes utilizan HTTPS, tu servidor debe tener un certificado TLS o SSL válido, correctamente configurado e instalado. No se admiten los certificados autofirmados.

En las secciones que figuran a continuación, se explica qué incluye cada tipo de solicitud y cómo responder a cada una de ellas. De manera alternativa, puedes usar nuestra app de ejemplo, que ya está configurada para procesar esas solicitudes.

Solicitudes de verificación

Siempre que configures el producto Webhooks en el panel de apps, enviaremos una solicitud GET a la URL del punto de conexión. Las solicitudes de verificación incluyen los siguientes parámetros de cadenas de consulta, como anexos al final de la URL del punto de conexión. Se verán similares a lo 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 estará configurado como `subscribe`.
`hub.challenge`	`1158201444`	Un `int` que debes volver a transmitirnos.
`hub.verify_token`	`meatyhamhock`	Una cadena que tomamos del campo Token de verificación en el panel de apps de tu app. Configurarás esta cadena cuando completes los pasos de los parámetros de configuración de Webhooks.

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

Validación de solicitudes de verificación

Cada vez que el punto de conexión recibe una solicitud de verificación, debe hacer lo siguiente:

Verificar que el valor de hub.verify_token coincida con la cadena configurada en el campo Token de verificación al configurar el producto Webhooks en el panel de tu app (aún no configuraste esta cadena de token).
Responder con el valor hub.challenge.

Si estás en tu panel de apps y configuras el producto Webhooks (y, por lo tanto, activas una solicitud de verificación), el panel indicará si el punto de conexión validó correctamente la solicitud. Si utilizas el punto de conexión /app/subscriptions de la API Graph para configurar el producto Webhooks, la API indicará si la operación fue exitosa o no con una respuesta.

Notificaciones de eventos

Cuando configures tu producto Webhooks, te suscribirás a campos (fields) específicos en un tipo de objeto (object) (por ejemplo, el campo photos en el objeto user). Siempre que haya un cambio en uno de esos campos, enviaremos a tu punto de conexión una solicitud POST con una carga JSON que describe el cambio.

Por ejemplo, si te suscribiste al campo photos del objeto user, y uno de los usuarios de tu app publicó una foto, te enviaremos una solicitud POST similar a la 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

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

Damos formato JSON a todas las cargas para que puedas analizarlas con paquetes o métodos de análisis JSON comunes.

No almacenamos los datos de las notificaciones de eventos de webhook que te enviamos. Por lo tanto, debes asegurarte de capturar y almacenar todo el contenido de carga que quieras conservar.

La mayoría de las cargas incluyen las siguientes propiedades comunes, pero el contenido y la estructura de cada carga varía según los campos del objeto a los que estés suscrito. Consulta la documentación de referencia de cada objeto para ver los campos que incluirá.

Propiedad	Descripción	Tipo
`object`	El tipo de objeto (por ejemplo, `user`, `page`, etc.)	`string`
`entry`	Una matriz que incluye un objeto que describe los cambios. Es posible agrupar por lotes varios cambios de diferentes objetos que son del mismo tipo.	`array`
`id`	El identificador del objeto	`string`
`changed_fields`	Una matriz de cadenas que indican los nombres de los campos que se modificaron. Solo se incluye si desactivaste el parámetro Incluir valores al configurar el producto Webhooks en el panel de apps de tu app.	`array`
`changes`	Una matriz que incluye un objeto que describe los campos modificados y sus nuevos valores. Solo se incluye si activaste el parámetro Incluir valores al configurar el producto Webhooks en el panel de apps de tu app.	`array`
`time`	Una marca de tiempo de UNIX que indica el momento en que se envió la notificación del evento (no el momento en que se produjo el cambio que disparó la notificación).	`int`

Validación de cargas

Firmamos todas las cargas útiles de las notificaciones de eventos con una firma SHA256 e incluimos la firma en el encabezado X-Hub-Signature-256 de la solicitud, precedido por sha256=. No es obligatorio que valides la carga, pero conviene hacerlo.

Para validar la carga:

Genera una firma SHA256 con la carga y con la clave secreta de la app.
Compara tu firma con la del encabezado X-Hub-Signature-256 (todo lo que aparece después de sha256=). Si las firmas coinciden, la carga es genuina.

Respuesta a notificaciones de eventos

Tu punto de conexión debe responder a todas las notificaciones de eventos con 200 OK HTTPS.

Frecuencia

Las notificaciones de eventos se recopilan y se envían en un lote de hasta 1.000 actualizaciones como máximo. Sin embargo, los lotes no siempre funcionan, así que asegúrate de que los servidores puedan administrar cada webhook de manera individual.

Si falla alguna actualización enviada a tu servidor, volveremos a intentar la operación inmediatamente y, después, unas cuantas veces más, con una frecuencia cada vez menor, durante las siguientes 36 horas. Tu servidor deberá manejar la desduplicación en esos casos. Después de 36 horas, se descartarán las respuestas que no se hayan aceptado.

Nota: La frecuencia con la que se envían las notificaciones de eventos de Messenger es diferente. Consulta la documentación sobre los webhooks de la plataforma de Messenger para obtener más información.

Configurar el producto Webhooks

Una vez que el punto de conexión o la app de ejemplo estén listos, usa el panel de apps de tu app para agregar y configurar el producto Webhooks. También puedes hacer esto de manera programática mediante el punto de conexión /{app-id}/subscriptions para todos los webhooks, a excepción de Instagram.

En este ejemplo, utilizaremos el panel para configurar un webhook que se suscribe a cualquier cambio en las fotos de cualquiera de los usuarios de tu app.

En el panel de apps, ve a Productos > Webhooks, selecciona Usuario en el menú desplegable y, a continuación, haz clic en Suscribirse a este objeto.
Selección del objeto del usuario.
Ingresa la URL del punto de conexión en el campo URL de devolución de llamada y una cadena en el campo Token de verificación. Incluiremos esta cadena en todas las solicitudes de verificación. Si usas una de nuestras apps de ejemplo, debe ser la misma cadena que usaste para la variable de configuración TOKEN.
Si quieres que las cargas de notificación del evento incluyan los nombres de los campos que cambiaron además de los nuevos valores, define la opción Incluir valores en Sí.
Ingreso de una URL de punto de conexión y una cadena de token de verificación.
Luego de hacer clic en Verificar y guardar, enviaremos al punto de conexión una solicitud de verificación que debes validar. Si el punto de conexión valida exitosamente la solicitud, deberías ver esto:
Validación exitosa.
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 "Fotos" en el objeto "Usuario".
Si el punto de conexión está configurado correctamente, debería validar la carga útil y ejecutar el código que hayas configurado para que se ejecute después de una validación exitosa. Si usas nuestra app de ejemplo, carga la URL de la app en el navegador web. Debería mostrar el contenido de la carga:
App de ejemplo que muestra la carga de notificación de prueba.

Próximos pasos

Ahora que sabes cómo configurar webhooks, quizás te resulte conveniente consultar nuestros documentos complementarios, donde se describen los pasos adicionales necesarios para configurar webhooks para productos específicos: