Webhooks

Información general

Webhooks permite que las apps de integración personalizada se suscriban a eventos en Workplace y reciban 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 cada una de las apps de integración personalizada que están suscritas al tema del webhook pertinente.

De esta manera, las apps resultan más eficientes, porque identifican cuando se produce un cambio, y, entonces, deja de ser necesario que usen solicitudes de la API Graph continuas o, incluso, periódicas para obtener el último contenido.

El marco que utiliza Webhooks de la API Graph es el mismo que permite que el webhook sea compatible para Workplace.

Suscripción a los temas del webhook

El cuadro de diálogo Editar integración personalizada proporciona pestañas a los temas del webhook que están disponibles para las apps en Workplace.

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

Para agregar una nueva suscripción al webhook en relación con un tema específico, proporciona una URL de devolución de llamada y un token de verificación. Luego, selecciona los campos de suscripción que sean necesarios para la funcionalidad que ofrecerá tu app.

Solo puedes suscribir una URL por tema del webhook, pero sí puedes utilizar la misma URL para varios temas.

Manejo de solicitudes de verificación

Cuando agregas una nueva suscripción o modificas una que ya existe, los servidores de Meta realizarán una solicitud GET a tu URL de devolución de llamada para verificar que el servidor de devolución de llamada sea válido.

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

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 cuando creaste la suscripción.

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

Verificar que el valor hub.verify_token coincida con la cadena que estableciste en el campo "Token de verificación" al configurar el webhook.
Responder con el valor hub.challenge.

Seguridad del webhook

Todas las llamadas de webhook a las URL de devolución de llamada que definió el desarrollador se realizan a través de HTTPS, lo que garantiza la seguridad a nivel de transporte de las cargas del webhook.

Con el fin de proporcionar seguridad adicional, se incluye una X-Hub-Signature-256 de encabezado HTTP en cada carga útil "POST", que se recomienda que utilices para verificar que la carga útil provino de un servidor de Meta.

Consulta la documentación sobre el Marco de webhook para obtener información detallada sobre este comportamiento.

Suscripción a webhooks con una llamada a la API

Es necesario que se realicen las llamadas a la API para leer o modificar las suscripciones a webhooks con un token de la app en vez de con el token de integración personalizada habitual. Se puede generar un token de la app concatenando el identificador de la app, un símbolo "|" y la clave secreta de la app.

Por ejemplo:

Datos	Cadena
Identificador de la app	504221332732118
Clave secreta de la app	d76ab3f35f3ff5aa6ffdc8637a660d2ea7
Token de la app:	504221332732118\|d76ab3f35f3ff5aa6ffdc8637a660d2ea7

Obtener suscripciones actuales a webhooks (con un token de la app)

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

Agregar suscripciones nuevas a webhooks (con un token de la app)

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}

Página de solución de problemas / suscripciones a apps

En los casos en los que no se reciben los webhooks de la forma esperada, se recomienda verificar que se haya configurado correctamente la suscripción entre la página y la app. Se debería configurar de manera automática, pero, en algunos casos, pueden producirse errores. Por ejemplo, si se produce un error durante un período prolongado al entregarse un webhook, se puede eliminar esta suscripción. Si se trata de apps de terceros, este error se mostrará como una alerta en el panel de apps.

Para verificar esta suscripción, se encuentran disponibles las siguientes llamadas a la API:

Obtener suscripciones actuales a apps y páginas (con un token de página)

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

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

Volver a crear suscripciones actuales a apps y páginas (con un token de página)

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

Temas de webhook

La actividad de Workplace se agrupa en temas. Cada uno de estos temas contiene un número de campos, que se asignan a eventos sobre un determinado tema. Las apps pueden suscribir actualizaciones de webhooks de cada uno de los temas y campos específicos dentro de los temas.

Workplace ofrece en estos momentos webhooks para los siguientes temas y grupos:

Página

Hay más información disponible en la documentación de referencia sobre Tema de la 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 Work Chat.
`message_deliveries`	Se activa cuando se entrega un mensaje que envió una página de integración personalizada (bot).
`messaging_postbacks`	Se activa cuando se presiona un botón de postback en Work Chat.
`message_reads`	Se activa cuando el destinatario lee un mensaje que se envió desde una página de integración personalizada (bot).

Grupos

Hay más información disponible en la documentación de referencia sobre el tema Grupo.

Campo de suscripción	Comportamiento
`posts`	Se activa cuando se agrega, actualiza o elimina una publicación en un grupo.
`comments`	Se activa cuando se agrega, actualiza o elimina un nuevo comentario en una publicación de un grupo.
`membership`	Se activa cuando cambian los miembros de un grupo.
`membership_requests`	Se activa cuando un usuario solicita ser miembro de un grupo.

Usuario

Hay más información disponible en la documentación de referencia sobre el tema Usuario.

Campo de suscripción	Comportamiento
`status`	Se activa cuando un usuario hace una publicación o edita la actualización de estado de un nuevo perfil. Se incluye también las publicaciones en la biografía de un usuario.
`events`	Se activa cuando un usuario crea, acepta o rechaza un evento.
`message_sends`	Se activa cuando un usuario envía un mensaje de Workplace Chat.
`message_unsends`	Se activa cuando un usuario elimina para todos un mensaje en una conversación de Workplace Chat.
`timeline_comments`	Se activa cuando hay un comentario en una publicación en la biografía de un usuario.

Seguridad

Hay más información disponible en la documentación de referencia sobre Tema de seguridad.

`admin_activity`

Los eventos que se activan cuando se agrega un administrador a una comunidad de Workplace o se lo elimina de dicha comunidad.

Evento	Comportamiento
`admin_set_to_unclaimed`	Un administrador configuró el estado de la cuenta de un usuario en No reclamada desde el panel para administradores o a través de la API de administración de cuentas.
`admin_force_log_out`	Un administrador obligó desde el panel para administradores a un usuario a cerrar sesión en todos los dispositivos.
`admin_deactivate`	Un administrador desactivó una cuenta desde el panel para administradores o a través de la API de administración de cuentas.
`admin_activate_account`	Un administrador activó una cuenta desde el panel para administradores o a través de la API de administración de cuentas.
`force_password_reset`	Un administrador obligó desde el panel para administradores a un usuario a restablecer su contraseña.
`admin_create_account`	Un administrador creó una cuenta desde el panel para administradores.

`compromised_credentials`

Los eventos que se activan cuando sospechamos que las contraseñas de Workplace de algunas cuentas de usuario de una comunidad pueden estar en riesgo.

Evento	Comportamiento
`found_compromised_credentials`	Workplace encontró credenciales comprometidas.

`files`

Los eventos que se activan con la actividad de los archivos de Workplace.

Evento	Comportamiento
`group_file_upload`	Un usuario subió un archivo a un grupo.
`group_file_download`	Un usuario descargó un archivo de un grupo.
`file_upload_malware_found`	Se identificó que un archivo subido contiene malware.

`groups`

Los eventos que se activan cuando una persona crea un grupo entre empresas en Workplace o se une a uno.

Evento	Comportamiento
`mcg_join`	Un usuario de la comunidad se unió a un grupo entre empresas.
`mcg_create`	Un usuario de la comunidad creó un grupo entre empresas.

`integrations`

Los eventos que se activan cuando un administrador crea o cambia propiedades de la integración.

Evento	Comportamiento
`custom_integration_create`	Un administrador que creó una integración personalizada.
`custom_integration_edit`	Un administrador que editó una integración personalizada.
`custom_integration_delete`	Un administrador que eliminó una integración personalizada.
`custom_integration_token_reset`	Un administrador generó un nuevo token de acceso para una integración personalizada.
`content_app_install`	Un usuario creó una integración de contenido.
`content_app_uninstall`	Un usuario desinstaló una integración de contenido.

`invites`

Los eventos que se activan cuando una persona se une a Workplace con una autoinvitación.

Evento	Comportamiento
`coworker_invite_sent`	Un usuario invitó a un compañero de trabajo a que se una a la comunidad.
`self_invite_sent`	Un usuario solicitó un correo electrónico de invitación para sí mismo.

`passwords`

Los eventos que se activan cuando una persona cambia su contraseña o solicita un restablecimiento de la contraseña.

Evento	Comportamiento
`password_change`	Se cambió la contraseña de un usuario después de finalizar el proceso de recuperación de la contraseña o a través de la configuración de la cuenta.
`password_reset_request`	Se inició el proceso de recuperación de la contraseña de un usuario, y se envió un código a la dirección de correo electrónico de dicho usuario.
`password_reset_wrong_code`	Un usuario ingresó un código de recuperación de la contraseña incorrecto.
`password_reset_success`	Finalizó correctamente el proceso de recuperación de la contraseña de un usuario.

`sessions`

Los eventos que se activan cuando una persona inicia o cierra sesión en Workplace.

Evento Comportamiento

Evento	Comportamiento
`log_in`	El usuario inició sesión en Workplace con contraseña o inicio de sesión único (SSO) en internet o en apps para celulares.
`log_out`	El usuario cerró la sesión en Workplace con contraseña o inicio de sesión único (SSO) en internet o en apps para celulares. No incluye el cierre de sesión forzoso impuesto por el administrador (ver `admin_force_log_out`).

log_in

El usuario inició sesión en Workplace con contraseña o inicio de sesión único (SSO) en internet o en apps para celulares.

log_out

El usuario cerró la sesión en Workplace con contraseña o inicio de sesión único (SSO) en internet o en apps para celulares.

No incluye el cierre de sesión forzoso impuesto por el administrador (ver admin_force_log_out).

`two_factor`

Los eventos que se activan cuando una persona habilita o deshabilita la autenticación en dos pasos.

Evento	Comportamiento
`two_factor_enable`	Un usuario activó la autenticación en dos pasos en la pestaña Configuración. Esto no captura cuando una persona confirma un teléfono determinado, pero indica que la función estaba activada.
`two_factor_disable`	Un usuario desactivó la autenticación en dos pasos en la pestaña Configuración. Esto no captura cuando una persona desactiva los dos pasos para un teléfono determinado, pero indica que la función estaba desactivada.
`add_two_factor_phone`	Un usuario agregó y confirmó un teléfono que se utilizó para la autenticación en dos pasos.
`two_factor_code_success`	Un usuario ingresó un código de autenticación en dos pasos válido al iniciar sesión en el sitio web o en el sitio web para celulares de Workplace.
`two_factor_code_failure`	Un usuario ingresó un código de autenticación en dos pasos inválido al iniciar sesión en el sitio web o en el sitio web para celulares de Workplace.
`two_factor_code_success_m`	Un usuario ingresó un código de autenticación en dos pasos válido al iniciar sesión en una app para celulares de Workplace para iOS o Android.
`two_factor_code_failure_m`	Un usuario ingresó un código de autenticación en dos pasos inválido al iniciar sesión en una app para celulares de Workplace para iOS o Android.

`reseller_events`

Eventos relacionados con un revendedor.

Evento	Comportamiento
`reseller_user_added`	Permite que un usuario no administrador de una empresa minorista vea la consola del revendedor.
`reseller_user_removed`	No permite que un usuario no administrador de una empresa minorista vea la consola del revendedor.
`reseller_invite_sent`	El revendedor invita a otra empresa a que se vincule con este.
`reseller_invite_accepted`	Una empresa acepta la invitación del revendedor para que se vinculen.
`reseller_invite_declined`	Una empresa rechaza la invitación del revendedor para que se vinculen.

Enlaces

Hay más información disponible en la documentación de referencia sobre Tema de enlace.

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

Biblioteca de recursos

Más información disponible en la categoría de documentos de la API Graph de la biblioteca de recursos.

Campo de suscripción	Comportamiento
`categories`	Se activa cuando se agrega, actualiza o elimina contenido en la biblioteca de recursos, o cuando se actualiza el público de lectura.
`comments`	Se activa cuando se agrega, actualiza o elimina un nuevo comentario en la biblioteca de recursos.
`quicklinks`	Se activa cuando se agrega, actualiza o elimina el enlace rápido de la biblioteca de recursos.