Webhooks

Información general

Gracias a los webhooks, las aplicaciones de integración personalizada pueden suscribirse a eventos en Workplace y recibir actualizaciones en tiempo real. Cuando se produce un cambio en Workplace, se envía una solicitud HTTPS POST a una URL de devolución de llamada para todas las aplicaciones de integración personalizada suscritas al tema pertinente del webhook.

De esta forma, las aplicaciones son más eficientes, ya que saben exactamente el momento en el que se ha producido un cambio y no tienen que basarse en las solicitudes a la API Graph continuas o, incluso, periódicas para obtener el contenido más reciente.

El mismo marco que impulsa Webhooks para la API Graph es el que proporciona la compatibilidad de los webhooks con Workplace.

Suscripción a temas de los webhooks

El cuadro de diálogo Editar integración personalizada proporciona pestañas para todos los temas de los webhooks disponibles para las aplicaciones en Workplace.

La sección Webhooks en el cuadro de diálogo Editar integración personalizada

Para añadir una nueva suscripción a un webhook sobre un tema determinado, debes proporcionar una dirección URL de devolución de llamada y un identificador de verificación y, a continuación, seleccionar los campos de suscripción que necesitas para la funcionalidad que proporcionará la aplicación.

Solo puedes suscribir una URL por tema de webhook, pero puedes usar la misma URL para varios temas.

Gestión de las solicitudes de verificación

Cuando añadas una suscripción nueva o modifiques una existente, los servidores de Meta realizarán una solicitud GET a tu URL de devolución de llamada para verificar la validez del servidor de devolución de llamada.

Se anexará una cadena de consulta a esta URL con los parámetros siguientes:

hub.mode: la cadena "subscribe" se pasa en este parámetro
hub.challenge: una cadena aleatoria
hub.verify_token: el valor verify_token que especificaste al crear la suscripción

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

Verificar que el valor hub.verify_token coincide con la cadena definida en el campo Identificador de verificación al configurar el webhook.
Responder con el valor de hub.challenge.

Seguridad de webhooks

Todas las llamadas de los webhooks a direcciones URL de devolución de llamada definidas por el desarrollador se realizan mediante HTTPS, lo que garantiza la seguridad de las cargas útiles de los webhooks en el transporte.

Con el fin de proporcionar seguridad adicional, se incluye un encabezado X-Hub-Signature-256 en HTTP en cada carga útil de POST; deberías usarlo para verificar que la carga útil procede de un servidor de Meta.

Para obtener información detallada de este comportamiento, consulta la documentación sobre el marco de los webhooks.

Suscripción a webhooks con una llamada a la API

Las llamadas a la API para leer o modificar suscripciones a webhooks deben realizarse con un identificador de aplicación en lugar de con el identificador de integración personalizado habitual. Se puede generar un identificador de aplicación concatenando el identificador de la aplicación, un carácter "|" y la clave secreta de la aplicación.

Por ejemplo:

Datos	Cadena
Identificador de la aplicación	504221332732118
Clave secreta de la aplicación	d76ab3f35f3ff5aa6ffdc8637a660d2ea7
Identificador de la aplicación:	504221332732118\|d76ab3f35f3ff5aa6ffdc8637a660d2ea7

Obtener las suscripciones actuales a webhooks (con el identificador de la aplicación)

GET graph.facebook.com
  /{app-id}/subscriptions
    &access_token={your_app_token}

Añadir una suscripción nueva a un webhook (con el identificador de la aplicación)

POST graph.facebook.com
  /{app-id}/subscriptions
    ?object=page
    &fields=mention,messages
    &callback_url={your-url}
    &verify_token={your-verify-token}
    &access_token={your_app_token}

Solución de problemas con las suscripciones a páginas o aplicaciones

En caso de que no recibas los webhooks como esperabas, te recomendamos que compruebes que la suscripción entre la página y la aplicación esté configurada correctamente. Esto debería haberse configurado de forma automática, pero podría no ser así en algunos casos. Por ejemplo, si se produce un error al entregar los webhooks durante un periodo de tiempo prolongado, puedes eliminar esta suscripción. En el caso de las aplicaciones de terceros, esto generará una alerta en el panel de aplicaciones.

Para comprobar esta suscripción, están disponibles las siguientes llamadas a la API:

Obtener la suscripción actual a una aplicación o una página (con el identificador de la aplicación)

GET graph.facebook.com
  /me/subscribed_apps?access_token={your_page_token}

Para volver a crear esta suscripción, están disponibles las siguientes llamadas a la API:

Volver a crear la suscripción actual a una aplicación o una página (con el identificador de la aplicación)

POST graph.facebook.com
  /me/subscribed_apps?access_token={your_page_token}
	{"subscribed_fields": ["messages"...]}

Temas de webhooks

La actividad de Workplace está agrupada en temas. Cada tema tiene una serie de campos que se asignan a eventos de un tema determinado. Las aplicaciones pueden suscribirse a actualizaciones de webhooks de cada uno de los temas y campos específicos dentro de cada tema.

Actualmente, Workplace proporciona webhooks para los temas y grupos siguientes:

Página

Encontrarás más información en los documentos de referencia sobre los temas de página.

Campo de suscripción	Comportamiento
`mention`	Se activa cuando se menciona una página de integración personalizada (bot) en un grupo.
`messages`	Se activa cuando se envía un mensaje a una página de integración personalizada (bot) en un chat de Workplace.
`message_deliveries`	Se activa cuando se entrega un mensaje que ha enviado una página de integración personalizada (bot).
`messaging_postbacks`	Se activa cuando se pulsa un botón de postback en el chat de Workplace.
`message_reads`	Se activa cuando el destinatario lee un mensaje de una página de integración personalizada (bot).

Grupos

Encontrarás más información en los documentos de referencia sobre los temas de grupo.

Campo de suscripción	Comportamiento
`posts`	Se activa cuando se añade, se actualiza o se elimina una publicación en un grupo.
`comments`	Se activa cada vez que se añade, se actualiza o se elimina un comentario nuevo en una publicación de un grupo.
`membership`	Se activa cuando cambia la pertenencia de un grupo.
`membership_requests`	Se activa cuando un usuario solicita la pertenencia a un grupo.

Usuario

Encontrarás más información en los documentos de referencia sobre los temas de usuario.

Campo de suscripción	Comportamiento
`status`	Se activa cuando un usuario publica o edita una actualización de estado en su perfil. Esto incluye las publicaciones en la biografía de un usuario.
`events`	Se activa cada vez que un usuario crea, acepta o rechaza un evento.
`message_sends`	Se activa cada vez que un usuario envía un mensaje de chat de Workplace.
`message_unsends`	Se activa cada vez que un usuario elimina un mensaje de chat de Workplace para todos los participantes de un hilo.
`timeline_comments`	Se activa cada vez que hay un comentario en una publicación en la biografía de un usuario.

Seguridad

Encontrarás más información en los documentos de referencia sobre los temas de seguridad.

`admin_activity`

Eventos que se activan cuando se añade o elimina un administrador de una comunidad de Workplace.

Evento	Comportamiento
`admin_set_to_unclaimed`	Un administrador ha definido el estado de la cuenta de un usuario en No reclamada desde el panel para administradores o mediante la API de administración de cuentas.
`admin_force_log_out`	Un administrador ha forzado el cierre de sesión de un usuario en todos los dispositivos desde el panel para administradores.
`admin_deactivate`	Un administrador ha desactivado una cuenta desde el panel para administradores o mediante la API de administración de cuentas.
`admin_activate_account`	Un administrador ha activado una cuenta desde el panel para administradores o mediante la API de administración de cuentas.
`force_password_reset`	Un administrador ha forzado el restablecimiento de la contraseña de un usuario desde el panel para administradores.
`admin_create_account`	Un administrador ha creado una cuenta desde el panel para administradores.

`compromised_credentials`

Eventos que se activan cuando sospechamos que las contraseñas de Workplace de algunas cuentas de usuario de una comunidad podrían estar en riesgo.

Evento	Comportamiento
`found_compromised_credentials`	Workplace ha encontrado credenciales comprometidas.

`files`

Eventos que se activan cuando hay actividad en un archivo de Workplace.

Evento	Comportamiento
`group_file_upload`	Un usuario ha subido un archivo a un grupo.
`group_file_download`	Un usuario ha descargado un archivo de un grupo.
`file_upload_malware_found`	Se ha detectado que un archivo subido contiene malware.

`groups`

Eventos que se activan cuando una persona crea un grupo entre empresas de Workplace o se une a uno.

Evento	Comportamiento
`mcg_join`	Un usuario de la comunidad se ha unido a un grupo entre empresas.
`mcg_create`	Un usuario de la comunidad ha creado un grupo entre empresas.

`integrations`

Eventos que se activan cuando un administrador crea o cambia las propiedades de una integración.

Evento	Comportamiento
`custom_integration_create`	Un administrador ha creado una integración personalizada.
`custom_integration_edit`	Un administrador ha editado una integración personalizada.
`custom_integration_delete`	Un administrador ha eliminado una integración personalizada.
`custom_integration_token_reset`	Un administrador ha generado un identificador de acceso nuevo para una integración personalizada.
`content_app_install`	Un usuario ha creado una integración de contenido.
`content_app_uninstall`	Un usuario ha desinstalado una integración de contenido.

`invites`

Eventos que se activan cuando un usuario se une a Workplace con una autoinvitación.

Evento	Comportamiento
`coworker_invite_sent`	Un usuario ha invitado a un compañero de trabajo a unirse a la comunidad.
`self_invite_sent`	Un usuario ha solicitado un correo electrónico de invitación para sí mismo.

`passwords`

Eventos que se activan cuando un usuario cambia su contraseña o solicita un restablecimiento de contraseña.

Evento	Comportamiento
`password_change`	Se ha cambiado la contraseña de un usuario después de completar el proceso de recuperación de la contraseña o bien mediante la configuración de la cuenta.
`password_reset_request`	Se ha iniciado un flujo de recuperación de la contraseña de un usuario y se ha enviado un código a la dirección de correo electrónico del usuario.
`password_reset_wrong_code`	Un usuario ha introducido un código de recuperación incorrecto para restablecer la contraseña.
`password_reset_success`	Se ha completado correctamente el flujo de recuperación de la contraseña de un usuario.

`sessions`

Eventos que se activan cuando un usuario inicia o cierra sesión en Workplace.

Evento Comportamiento

Evento	Comportamiento
`log_in`	Un usuario ha iniciado sesión en Workplace con contraseña o inicio de sesión único mediante la web o la aplicación para móviles.
`log_out`	Un usuario ha cerrado sesión en Workplace con contraseña o inicio de sesión único mediante la web o la aplicación para móviles. No incluye el cierre de sesión forzado iniciado por un administrador (consulta `admin_force_log_out`)

log_in

Un usuario ha iniciado sesión en Workplace con contraseña o inicio de sesión único mediante la web o la aplicación para móviles.

log_out

Un usuario ha cerrado sesión en Workplace con contraseña o inicio de sesión único mediante la web o la aplicación para móviles.

No incluye el cierre de sesión forzado iniciado por un administrador (consulta admin_force_log_out)

`two_factor`

Eventos que se activan cuando una persona activa o desactiva la autenticación en dos pasos.

Evento	Comportamiento
`two_factor_enable`	Un usuario ha activado la autenticación en dos pasos en la pestaña Configuración. Esto no incluye los casos en los que un usuario confirma un teléfono particular, pero indica que se ha activado la función.
`two_factor_disable`	Un usuario ha desactivado la autenticación en dos pasos en la pestaña Configuración. Esto no incluye los casos en los que un usuario desactiva los dos pasos para un teléfono particular, pero indica que se ha desactivado la función.
`add_two_factor_phone`	Un usuario ha añadido y confirmado un teléfono que se usará para la autenticación en dos pasos.
`two_factor_code_success`	Un usuario ha introducido un código válido para la autenticación en dos pasos al iniciar sesión en el sitio web o en el sitio web para móviles de Workplace.
`two_factor_code_failure`	Un usuario ha introducido un código no válido para la autenticación en dos pasos al iniciar sesión en el sitio web o en el sitio web para móviles de Workplace.
`two_factor_code_success_m`	Un usuario ha introducido un código válido para la autenticación en dos pasos al iniciar sesión en la aplicación para móviles iOS o Android de Workplace.
`two_factor_code_failure_m`	Un usuario ha introducido un código no válido para la autenticación en dos pasos al iniciar sesión en la aplicación para móviles iOS o Android de Workplace.

`reseller_events`

Eventos relacionados con un revendedor.

Evento	Comportamiento
`reseller_user_added`	Permite que un usuario que no es administrador de una empresa revendedora vea la consola para revendedores.
`reseller_user_removed`	Elimina el permiso para que un usuario que no es administrador de una empresa revendedora vea la consola para revendedores.
`reseller_invite_sent`	Una empresa revendedora invita a otra empresa para que esté vinculada a ella.
`reseller_invite_accepted`	Una empresa acepta la invitación de un revendedor para estar vinculados.
`reseller_invite_declined`	Una empresa rechaza la invitación de un revendedor para estar vinculados.

Enlaces

Encontrarás más información en los documentos de referencia sobre los temas de enlace.

Evento	Comportamiento
`preview`	Metadatos sobre el usuario que solicita acceso a enlaces que se pueden compartir.
`collection`	Metadatos de un enlace compartido en Workplace para generar una vista previa.

Biblioteca de conocimiento

Encontrarás más información en los documentos de la API Graph sobre categorías de la Biblioteca de conocimiento.

Campo de suscripción	Comportamiento
`categories`	Se activa cuando se añade, se actualiza o se elimina contenido de la Biblioteca de conocimiento o cuando se actualiza la audiencia de lectura.
`comments`	Se activa cada vez que se añade, se actualiza o se elimina un comentario nuevo en la Biblioteca de conocimiento.
`quicklinks`	Se activa cuando se añade, se actualiza o se elimina un enlace rápido de la Biblioteca de conocimiento.