Introdução

Este documento explica como configurar um Webhook que notificará você sempre que os usuários do seu app publicarem alterações nas fotos deles. Quando você entender como configurar este Webhook, saberá como configurar todos os Webhooks.

Para configurar um Webhook, é necessário fazer o seguinte:

Criar um ponto de extremidade em um servidor seguro que possa processar solicitações HTTPS.
Configurar o produto Webhooks no Painel de Apps.

Essas etapas são explicadas com mais detalhes abaixo.

Como criar um ponto de extremidade

Seu ponto de extremidade deve processar dois tipos de solicitação HTTPS: solicitações de verificação e notificações de evento. Como as duas solicitações usam HTTPS, o servidor deve ter um certificado TLS ou SSL válido configurado e instalado corretamente. Os certificados autoatribuídos não são suportados.

As seções abaixo explicam qual o conteúdo de cada tipo de solicitação e como responder a elas. Como alternativa, use o nosso exemplo de app que já está configurado para processar essas solicitações.

Solicitações de verificação

Enviaremos uma solicitação GET para a URL do ponto de extremidade sempre que você configurar o produto Webhooks no Painel de Apps. As solicitações de verificação incluirão os seguintes parâmetros da string de consulta, anexados ao final da URL do ponto de extremidade. Elas serão assim:

Exemplo de solicitação de verificação

GET https://www.your-clever-domain-name.com/webhooks? hub.mode=subscribe& hub.challenge=1158201444& hub.verify_token=meatyhamhock

Parâmetro	Exemplo de valor	Descrição
`hub.mode`	`subscribe`	Esse valor será sempre definido como `subscribe`.
`hub.challenge`	`1158201444`	Um `int` que você deve retornar para nós.
`hub.verify_token`	`meatyhamhock`	Uma string obtida no campo Verificar token no Painel de Apps. Você definirá essa string quando concluir as etapas de configuração dos Webhooks.

Observação: o PHP converte pontos (.) em sublinhados (_) nos nomes dos parâmetros.

Como validar as solicitações de verificação

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

verificar se o valor hub.verify_token corresponde à string definida no campo Verificar token quando você configura o produto Webhooks no Painel de Apps (você ainda não configurou essa string do token);
responder com o valor hub.challenge.

Se você estiver no Painel de Apps e configurar o produto Webhooks (e isso acionará uma solicitação de verificação), o painel indicará se o ponto de extremidade validou a solicitação corretamente. Se você usar o ponto de extremidade /app/subscriptions da Graph API para configurar o produto Webhooks, a API indicará sucesso ou falha com uma resposta.

Notificações de eventos

Na configuração do produto Webhooks, você se inscreverá em fields específicos em um tipo object (por exemplo, o campo photos no objeto user). Sempre que houver uma mudança em um desses campos, enviaremos uma solicitação POST para o seu ponto de extremidade com uma carga JSON descrevendo a alteração.

Por exemplo, se você assinar o campo photos do objeto do user e um dos usuários do app tiver publicado uma foto, enviaremos a você uma solicitação POST semelhante a:

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" }

Conteúdo da carga

As cargas conterão um objeto descrevendo a mudança. Ao configurar o produto Webhooks, você pode indicar se as cargas devem conter somente os nomes dos campos alterados ou se elas devem incluir também os novos valores.

Como formatamos todas as cargas com JSON, é possível analisar a carga usando métodos ou pacotes comuns de análise de JSON.

Nós não armazenamos dados de notificação de eventos do Webhook enviados, então, capture e armazene o conteúdo de todas as cargas que deseja manter.

A maioria das cargas conterá as propriedades comuns descritas a seguir, mas o conteúdo e a estrutura de cada carga variam dependendo dos campos do objeto em que você está inscrito. Consulte o documento de referência de cada objeto para ver quais campos serão incluídos.

Propriedade	Descrição	Tipo
`object`	O tipo do objeto (por exemplo, `user`, `page`, entre outros)	`string`
`entry`	Uma matriz contendo um objeto que descreve as alterações. Várias alterações de objetos diferentes, mas que são do mesmo tipo, podem ser agrupadas em lote.	`array`
`id`	O ID do objeto	`string`
`changed_fields`	Uma matriz de strings indicando os nomes dos campos que foram alterados. Ela será incluída somente se você desabilitar a configuração Incluir valores ao configurar o produto Webhooks no Painel de Apps.	`array`
`changes`	Uma matriz contendo um objeto que descreve os campos alterados e os seus novos valores. Ela será incluída somente se você habilitar a configuração Incluir valores ao configurar o produto Webhooks no Painel de Apps.	`array`
`time`	Um registro de data e hora do UNIX indicando quando a notificação do evento foi enviada (não quando ocorreu a alteração que acionou a notificação).	`int`

Como validar cargas

Nós assinamos todas as cargas de notificação de eventos com uma assinatura SHA256 e a incluímos no cabeçalho X-Hub-Signature-256 da solicitação, precedida por sha256=. Não é necessário validar a carga, mas é recomendado.

Para validar a carga:

gere uma assinatura SHA256 usando a carga e a chave secreta do app;
compare a sua assinatura com a do cabeçalho X-Hub-Signature-256 (tudo que aparece após sha256=). Se as assinaturas coincidirem, a carga será verdadeira.

Como responder a notificações de eventos

Seu ponto de extremidade deve responder a todas as notificações de eventos com 200 OK HTTPS.

Frequência

Notificações de eventos são agregadas e enviadas em um lote com no máximo 1.000 atualizações. No entanto, a criação de lotes não pode ser garantida. Por isso, ajuste os seus servidores para lidar com cada Webhook individualmente.

Se uma atualização enviada para o servidor falhar, tentaremos outra vez imediatamente e depois mais algumas vezes, diminuindo a frequência nas 36 horas seguintes. Seu servidor deverá lidar com a desduplicação nesses casos. As respostas não reconhecidas serão retiradas após 36 horas.

Observação: a frequência de envio das notificações de eventos do Messenger é diferente. Consulte a documentação sobre Webhooks para a plataforma do Messenger para saber mais.

Como configurar o produto Webhooks

Depois que o ponto de extremidade ou exemplo de app estiver pronto, use o Painel de Apps para adicionar e configurar o produto Webhooks. Isso também pode ser feito de modo programático usando o ponto de extremidade /{app-id}/subscriptions para todos os Webhooks exceto o Instagram.

Neste exemplo, usaremos o painel para configurar um Webhook que é inscrito nas alterações das fotos dos usuários do app.

No Painel de Apps, acesse Produtos > Webhooks, selecione User no menu suspenso e clique em Subscribe to this object.
Escolher o objeto do usuário.
Insira a URL do ponto de extremidade no campo URL de retorno de chamada e insira uma string no campo Verificar token. Incluiremos essa string em todas as solicitações de verificação. Se você estiver usando um dos nossos apps de exemplo, deverá ser a mesma string usada para a variável de configuração TOKEN do app.
Se você quiser que as cargas de notificação de eventos incluam os nomes dos campos que mudaram além dos novos valores, altere a opção Incluir valores para Sim.
Inserir uma URL de ponto de extremidade e uma string de token de verificação.
Depois que você clicar em Verificar e salvar, enviaremos uma solicitação de verificação para o seu ponto de extremidade, que você deverá validar. Se seu ponto de extremidade validar corretamente a solicitação, esta mensagem será exibida:
Validação bem-sucedida.
A última etapa é assinar campos individuais. Assine o campo photos e envie uma notificação de evento de teste.
Assinar o campo Fotos no objeto do usuário.
Se o ponto de extremidade for configurado corretamente, ele deverá validar a carga e executar o código que você configurou para processar caso a validação seja bem-sucedida. Se você usar o exemplo de app, carregue a URL do app no navegador da web. Ele deve exibir o conteúdo da carga:
Exemplo de app exibindo a carga de notificação de teste.

Próximas etapas

Agora que você sabe como configurar os Webhooks, consulte outros documentos que descrevem as etapas adicionais envolvidas ao configurar Webhooks para produtos específicos: