Webhooks

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.

A compatibilidade com webhooks no Workplace é fornecida pela mesma estrutura dos Webhooks para Graph API.

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 seção Webhooks no diálogo Editar integração personalizada

Para adicionar uma nova assinatura de webhook em um 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.

Como processar solicitações de verificação

Quando você adiciona ou modifica uma assinatura, os servidores da Meta fazem uma solicitação GET para a URL de retorno de chamada com o objetivo 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.

Sempre que seu ponto de extremidade receber uma solicitação de verificação, você deverá:

• verificar se o valor hub.verify_token corresponde à string configurada no campo Token de verificação do webhook;
• responder com o valor hub.challenge.

Segurança de webhooks

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, um cabeçalho HTTPX-Hub-Signature-256 é incluído em cada carga de POST. Use isso para verificar se uma carga veio de um servidor da Meta.

Para saber mais sobre esse comportamento, consulte a documentação sobre a estrutura dos webhooks.

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.

Como assinar webhooks usando uma chamada de API

As chamadas de API para ler ou modificar assinaturas de webhook precisam ser feitas com um token de app, em vez do token de integração personalizada padrão. O token do app é gerado pela concatenação do ID do app, do símbolo "|" e da chave secreta do app.

Por exemplo:

Obter assinaturas de webhook atuais (usando o token do app)

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

Adicionar nova assinatura de webhook (usando o token do 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}

Solucionar problemas com assinaturas entre a página e o app

Quando os webhooks não são recebidos conforme o esperado, recomendamos verificar se a assinatura entre a página e o app foi configurada corretamente. Essa configuração deve ocorrer de maneira automática, mas pode haver falhas. Por exemplo, se a entrega de um webhook falhar por um período prolongado, a assinatura poderá ser removida. Em apps de terceiros, isso resultará em um alerta no Painel de Apps.

Para verificar essa assinatura, use uma das chamadas de API abaixo:

Obter assinatura atual entre a página e o app (usando o token da página)

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

Para recriar essa assinatura, use uma das chamadas de API abaixo:

Recriar assinatura atual entre o app e a página (usando o token da página)

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

Tópicos de webhook

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

No momento, o Workplace fornece webhooks para estes tópicos e grupos:

Página

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

Grupos

Há mais informações disponíveis na documentação de referência sobre tópicos de grupos.

Usuário

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

Segurança

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

admin_activity

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

compromised_credentials

Eventos disparados quando suspeitamos que as senhas do Workplace de algumas contas de usuário em uma comunidade estão em risco.

files

Eventos disparados em atividades de arquivo no Workplace.

groups

Eventos disparados quando uma pessoa cria ou participa de um grupo multiempresarial (MCG, pelas iniciais em inglês) do Workplace.

integrations

Eventos disparados quando um administrador cria ou altera as propriedades de uma integração.

invites

Eventos disparados quando uma pessoa entra no Workplace via autoconvite.

passwords

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

sessions

Eventos disparados quando uma pessoa entra ou sai do Workplace.

two_factor

Eventos disparados quando uma pessoa habilita ou desabilita a autenticação de dois fatores.

reseller_events

Eventos relacionados a revendedores.

Links

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

Biblioteca de Conhecimento

Para mais informações, consulte a documentação sobre a categoria Biblioteca de Conhecimento da Graph API.