Primeiros passos

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.

Create an Endpoint

Your endpoint must be able to process two types of HTTPS requests: Verification Requests and Event Notifications. Since both requests use HTTPs, your server must have a valid TLS or SSL certificate correctly configured and installed. Self-signed certificates are not supported.

The sections below explain what will be in each type of request and how to respond to them. Alternatively, you can use our sample app which is already configured to process these requests.

Verification Requests

Anytime you configure the Webhooks product in your App Dashboard, we'll send a GET request to your endpoint URL. Verification requests include the following query string parameters, appended to the end of your endpoint URL. They will look something like this:

Sample Verification Request

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

Parameter	Sample Value	Description
`hub.mode`	`subscribe`	This value will always be set to `subscribe`.
`hub.challenge`	`1158201444`	An `int` you must pass back to us.
`hub.verify_token`	`meatyhamhock`	A string that that we grab from the Verify Token field in your app's App Dashboard. You will set this string when you complete the Webhooks configuration settings steps.

Note: PHP converts periods (.) to underscores (_) in parameter names.

Validating Verification Requests

Whenever your endpoint receives a verification request, it must:

Verify that the hub.verify_token value matches the string you set in the Verify Token field when you configure the Webhooks product in your App Dashboard (you haven't set up this token string yet).
Respond with the hub.challenge value.

If you are in your App Dashboard and configuring your Webhooks product (and thus, triggering a Verification Request), the dashboard will indicate if your endpoint validated the request correctly. If you are using the Graph API's /app/subscriptions endpoint to configure the Webhooks product, the API will indicate success or failure with a response.

Event Notifications

When you configure your Webhooks product, you will subscribe to specific fields on an object type (e.g., the photos field on the user object). Whenever there's a change to one of these fields, we will send your endpoint a POST request with a JSON payload describing the change.

For example, if you subscribed to the user object's photos field and one of your app's Users posted a Photo, we would send you a POST request that would look something like this:

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

Payload Contents

Payloads will contain an object describing the change. When you configure the webhooks product, you can indicate if payloads should only contain the names of changed fields, or if payloads should include the new values as well.

We format all payloads with JSON, so you can parse the payload using common JSON parsing methods or packages.

We do not store any Webhook event notification data that we send you, so be sure to capture and store any payload content that you want to keep.

Most payloads will contain the following common properties, but the contents and structure of each payload varies depending on the object fields you are subscribed to. Refer to each object's reference document to see which fields will be included.

Property	Description	Type
`object`	The object's type (e.g., `user`, `page`, etc.)	`string`
`entry`	An array containing an object describing the changes. Multiple changes from different objects that are of the same type may be batched together.	`array`
`id`	The object's ID	`string`
`changed_fields`	An array of strings indicating the names of the fields that have been changed. Only included if you disable the Include Values setting when configuring the Webhooks product in your app's App Dashboard.	`array`
`changes`	An array containing an object describing the changed fields and their new values. Only included if you enable the Include Values setting when configuring the Webhooks product in your app's App Dashboard.	`array`
`time`	A UNIX timestamp indicating when the Event Notification was sent (not when the change that triggered the notification occurred).	`int`

Validating Payloads

We sign all Event Notification payloads with a SHA256 signature and include the signature in the request's X-Hub-Signature-256 header, preceded with sha256=. You don't have to validate the payload, but you should.

To validate the payload:

Generate a SHA256 signature using the payload and your app's App Secret.
Compare your signature to the signature in the X-Hub-Signature-256 header (everything after sha256=). If the signatures match, the payload is genuine.

Responding to Event Notifications

Your endpoint should respond to all Event Notifications with 200 OK HTTPS.

Frequency

Event Notifications are aggregated and sent in a batch with a maximum of 1000 updates. However batching cannot be guaranteed so be sure to adjust your servers to handle each Webhook individually.

If any update sent to your server fails, we will retry immediately, then try a few more times with decreasing frequency over the next 36 hours. Your server should handle deduplication in these cases. Unacknowledged responses will be dropped after 36 hours.

Note: The frequency with which Messenger event notifications are sent is different. Please refer to the Messenger Platform Webhooks documentation for more information.

Como configurar o produto Webhooks

Depois que o ponto de extremidade ou o app de exemplo estiverem prontos, 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 Usuário no menu suspenso e clique em Assinar este objeto.
Escolher o objeto do usuário.
Insira o 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 um 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 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 o 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.

mTLS para Webhooks

Mutual TLS (mTLS) é um método para autenticação mútua.

O mTLS verifica se as partes em cada extremidade de uma conexão de rede têm a chave privada correta para confirmar que elas são quem dizem ser. As informações nos respectivos certificados TLS fornecem uma verificação adicional.

Como configurar o mTLS

Depois que você habilitar o mTLS na sua assinatura da conta do WhatsApp Business, a Meta apresentará um certificado de cliente com o certificado de intermediário assinante. Ambos os certificados são usados para criar um handshake do TLS de solicitações de webhook para seu servidor. Seu servidor poderá então verificar a identidade do remetente dessas solicitações por meio da cadeia de confiança e do nome comum (CN, na sigla em inglês).

O certificado de cliente é assinado por um certificado CA intermediário (CA DigiCert SHA2 High Assurance Server) e, depois, por um certificado CA raiz (CA DigiCert High Assurance EV Root). Além disso, o intermediário também assina o certificado para graph.facebook.com:

Verificação de certificado de cliente

Depois de configurar o HTTPS para receber solicitações de Webhook, conclua as seguintes etapas a fim de verificar o certificado do cliente e seu nome comum client.webhooks.fbclientcerts.com :

Instalar o certificado raiz
Verificar o certificado do cliente em relação ao certificado raiz
Verificar o nome comum (client.webhooks.fbclientcerts.com) do certificado do cliente

Observação: os servidores que recebem Webhooks devem estar usando HTTPS. Verificamos a segurança do nosso servidor de HTTPS constantemente.

Exemplo

Dependendo da configuração do seu servidor, os detalhes das etapas acima podem variar. Ilustramos com dois exemplos, um para Nginx e um para Application Load Balancer (ALB) da AWS.

Nginx

Baixe o certificado raiz (DigiCert High Assurance EV Root CA) do DigiCert para seu servidor, por exemplo, /etc/ssl/certs/DigiCert_High_Assurance_EV_Root_CA.pem.

Ative o mTLS por diretivas do Nginx (captura de tela de exemplo).

ssl_verify_client       on;
ssl_client_certificate  /etc/ssl/certs/DigiCert_High_Assurance_EV_Root_CA.pem;
ssl_verify_depth        3;

Verifique se o CN da variável incorporada ao Nginx $ssl_client_s_dn é igual a "client.webhooks.fbclientcerts.com" (exemplo de captura de tela)
```
if ($ssl_client_s_dn ~ "CN=client.webhooks.fbclientcerts.com") {
    return 200 "$ssl_client_s_dn";
}
```

Application Load Balancer (ALB) da AWS

Baixe o certificado intermediário (DigiCert SHA2 High Assurance Server CA) do DigiCert para um bucket do S3. O certificado raiz não é aceito pela AWS porque é assinado usando o algoritmo SHA1withRSA. Já o certificado intermediário, que é assinado usando SHA256withRSA, é aceito.
Configure o ouvinte HTTPS na ALB para habilitar o mTLS com o armazenamento de confiança contendo o certificado no bucket do S3 (exemplo de captura de tela).
No código do app, extraia o CN do cabeçalho HTTP “X-Amzn-Mtls-Clientcert-Subject” e verifique se é igual a “client.webhooks.fbclientcerts.com”.

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: