Webhooks - Documentação - Meta for Developers

Visão geral

Os webhooks possibilitam que apps de integração personalizada se inscrevam em eventos no Workplace e recebam atualizações em tempo real. Quando houver uma alteração no Workplace, uma solicitação HTTPS POST será enviada à URL de retorno de chamada correspondente a cada app de integração personalizada que assinou o tópico de webhook em questão.

Isso deixa os apps mais eficientes, pois eles sabem exatamente quando as mudanças acontecem, sem depender de solicitações constantes ou periódicas à Graph API para receber o conteúdo mais recente.

O suporte a webhooks do Workplace é oferecido pela mesma estrutura dos Webhooks para Facebook.

Como assinar tópicos de webhook

O diálogo Editar integração personalizada fornece abas para cada um dos tópicos de webhook disponíveis para os apps no Workplace.

A aba Webhooks no diálogo Editar integração personalizada

Para adicionar uma nova assinatura de webhook em determinado tópico, forneça uma URL de retorno de chamada e um token de verificação. Depois, selecione os campos de assinatura necessários para os recursos do app.

Só é possível assinar uma URL por tópico de webhook. No entanto, a mesma URL pode ser usada em vários tópicos.

Como processar solicitações de verificação

Quando você adiciona ou modifica uma assinatura, os servidores do Facebook fazem uma solicitação GET para a URL de retorno de chamada a fim de verificar a validade do servidor do retorno de chamada.

Uma string de consulta será adicionada à URL com os parâmetros a seguir:

hub.mode: a string subscribe é passada no parâmetro.
hub.challenge: uma string aleatória.
hub.verify_token: o valor verify_token que foi especificado na criação da assinatura.

Ao receber uma solicitação HTTP GET na sua URL de retorno de chamada, use o parâmetro verify_token para verificar se ela vem de um servidor do Facebook.

Segurança de webhook

Todas as chamadas para URLs de retorno de chamada definidas pelos desenvolvedores são feitas via HTTPS. Isso garante a segurança em nível de transporte para cargas de webhook.

Para obter mais segurança, o X-Hub-Signature-256 de um cabeçalho HTTP é incluído em cada carga de POST. Use-o para verificar se uma carga veio de um servidor do Facebook.

Para saber mais sobre esse comportamento, consulte a documentação sobre a estrutura de webhook do Facebook.

Tópicos de webhook

As atividades no Workplace são agrupadas por tópicos. Cada um deles tem campos conectados a eventos em um tópico específico. Além disso, os apps podem se inscrever para receber atualizações de webhook referente a cada tópico e campos específicos de cada tópico.

Atualmente, o Workplace fornece webhooks para os tópicos e grupos a seguir:

Página

Mais informações disponíveis na documentação de referência sobre tópicos de página.

Campo de assinatura	Comportamento
`mention`	Disparado quando uma página de integração personalizada (bot) é mencionada em um grupo.
`messages`	Disparado quando uma página de integração personalizada (bot) recebe uma mensagem no Work Chat.
`message_deliveries`	Disparado quando uma mensagem enviada por uma página de integração personalizada (bot) é entregue.
`messaging_postbacks`	Disparado quando um botão de postback é pressionado no Work Chat.
`message_reads`	Disparado quando uma mensagem de uma página de integração personalizada (bot) é lida pelo destinatário.

Grupo

Mais informações disponíveis na documentação de referência sobre tópicos de grupo.

Campo de assinatura	Comportamento
`posts`	Disparado quando uma publicação é adicionada, atualizada ou excluída em um grupo.
`comments`	Disparado sempre que um novo comentário é adicionado, atualizado ou excluído em uma publicação de grupo.
`membership`	Disparado quando os membros do grupo são alterados.

Usuário

Mais informações disponíveis na documentação de referência sobre tópicos de usuário.

Campo de assinatura	Comportamento
`status`	Disparado quando um usuário publica ou edita uma atualização de status no perfil dele.
`events`	Disparado toda vez que um usuário cria, aceita ou recusa um evento.
`message_sends`	Disparado toda vez que um usuário envia uma mensagem no Workplace Chat.

Link

Mais informações disponíveis na documentação sobre prévias autenticadas.

Campo de assinatura	Comportamento
`preview`	Disparado quando o Workplace precisa recuperar informações sobre uma URL.
`collection`	Relevante apenas para apps na lista de permissão que sejam compatíveis com a navegação hierárquica no editor de publicação.

Segurança

Para mais informações, consulte a documentação de referência sobre tópicos de segurança.

`sessions`

Eventos disparados quando uma pessoa entra ou sai do Workplace.

Evento Comportamento

Evento	Comportamento
`log_in`	O usuário entrou no Workplace com senha ou SSO, no www ou nos apps para celular.
`log_out`	O usuário saiu do Workplace com senha ou com SSO no www ou em apps para celular. Isso não inclui saída forçada pelo administrador (veja `admin_force_log_out`).

log_in

O usuário entrou no Workplace com senha ou SSO, no www ou nos apps para celular.

log_out

O usuário saiu do Workplace com senha ou com SSO no www ou em apps para celular.

Isso não inclui saída forçada pelo administrador (veja admin_force_log_out).

`passwords`

Eventos disparados quando uma pessoa altera a senha ou solicita a redefinição de senha.

Evento	Comportamento
`password_change`	A senha de um usuário foi alterada como resultado da recuperação de senha ou via configurações da conta.
`password_reset_request`	O fluxo de recuperação de senha de um usuário foi iniciado, e um código foi enviado para o endereço de email dele.
`password_reset_wrong_code`	Um usuário inseriu o código de recuperação de senha incorreto.
`password_reset_success`	O fluxo de recuperação de senha de um usuário foi concluído com sucesso.

`admin_activity`

Eventos disparados quando um administrador é adicionado ou removido de uma comunidade do Workplace.

Evento	Comportamento
`admin_set_to_unclaimed`	Um administrador configurou o estado de uma conta como não reivindicada no Painel Administrativo ou por meio da API de Gerenciamento de Contas.
`admin_force_log_out`	Um administrador forçou a saída de um usuário em todos os dispositivos pelo Painel Administrativo.
`admin_deactivate`	Um administrador desativou uma conta no Painel Administrativo ou por meio da API de Gerenciamento de Contas.
`admin_activate_account`	Um administrador ativou uma conta no Painel Administrativo ou por meio da API de Gerenciamento de Contas.
`force_password_reset`	Um administrador forçou a redefinição de senha de um usuário no Painel Administrativo.
`admin_create_account`	Um administrador criou um conta pelo Painel Administrativo.

`two_factor`

Eventos disparados quando uma pessoa ativa ou desativa a autenticação de dois fatores.

Evento	Comportamento
`two_factor_enable`	Um usuário ativou a autenticação de dois fatores na aba Configurações. Isso não captura quando alguém confirma um telefone, mas indica que o recurso foi ativado.
`two_factor_disable`	Um usuário desativou a autenticação de dois fatores na aba Configurações. Isso não detecta quando a autenticação é desativada em um telefone, mas indica que o recurso foi desativado.