1. Desenvolver um app consumidor de webhook
Para registrar um webhook no seu X app, você precisa desenvolver, implantar e hospedar um web app que receba eventos de webhook do X e responda às requisições de segurança CRC.Requisitos de URL
Crie um web app com uma URL HTTPS publicamente acessível que atuará como o endpoint de webhook para receber eventos:- O path do URI é sua escolha. Estes exemplos são todos válidos:
https://mydomain.com/service/listenhttps://mydomain.com/webhook/twitter
- A URL não pode incluir uma especificação de porta (por exemplo,
https://mydomain.com:5000/webhooknão funcionará)
O que seu app precisa lidar
Seu endpoint de webhook deve lidar com dois tipos de requisições HTTP:2. O CRC check
O Challenge-Response Check (CRC) é como o X valida que a URL de callback que você forneceu é válida e que você a controla. Seu web app deve responder corretamente às requisições de CRC para registrar e manter seu webhook.Quando o CRC é acionado
Se o seu webhook falhar em um CRC check, ele será marcado como
invalid e parará de receber eventos até que passe novamente.
Como o CRC funciona
Quando o X envia um CRC, ele faz uma requisição GET para sua URL de webhook com um parâmetro de consultacrc_token:
response_token:
Como construir a resposta do CRC
- Use o valor de
crc_tokendo parâmetro de consulta como a mensagem - Use o consumer secret (API secret key) do seu app como a chave
- Crie um hash HMAC SHA-256
- Faça o Base64 encode do resultado
- Adicione
sha256=como prefixo à string codificada
Exemplo: Python
Exemplo
Exemplo: Node.js
Exemplo
Exemplo: Flask (endpoint completo)
Este exemplo mostra um endpoint de webhook completo que lida com a validação CRC (GET) e a entrega de eventos (POST):Exemplo
3. Protegendo webhooks
As APIs baseadas em webhook do X fornecem dois métodos para confirmar a segurança do seu servidor de webhook:Challenge-Response Check (CRC)
O CRC permite que o X confirme a propriedade do web app que recebe eventos de webhook. Consulte a Etapa 2 acima para detalhes completos de implementação.Verificação de assinatura
Cada requisição POST do X inclui um headerx-twitter-webhooks-signature que permite confirmar que o X é a origem do webhook recebido.
Para verificar a assinatura:
- Obtenha o valor do header
x-twitter-webhooks-signatureda requisição recebida - Crie um hash HMAC SHA-256 usando seu consumer secret como chave e o corpo bruto da requisição como mensagem
- Faça o Base64 encode do hash e adicione
sha256=como prefixo - Compare o valor calculado com o valor do header — eles devem coincidir
Exemplo
4. Registrar seu webhook
Assim que seu app puder lidar com CRC checks, registre a URL do seu webhook fazendo uma requisiçãoPOST /2/webhooks. Quando você fizer essa requisição, o X enviará imediatamente uma requisição CRC para o seu web app para verificar a propriedade.
Todos os endpoints de gerenciamento de webhook requerem autenticação com OAuth2 App Only Bearer Token.
Criar um webhook
POST /2/webhooks — Referência da API
Visualizar webhooks
GET /2/webhooks — Referência da API
Recupere todas as configurações de webhook associadas à sua aplicação.
Exemplo de resposta
Excluir um webhook
DELETE /2/webhooks/:webhook_id — Referência da API
Exclua um webhook usando seu webhook_id (obtido na resposta de criação ou listagem).
Validar e reativar um webhook
PUT /2/webhooks/:webhook_id — Referência da API
Aciona um CRC check para o webhook informado. Se o check for bem-sucedido, o webhook é reativado com valid: true.
valid reflete o status após a tentativa de check. Você pode verificar o status atual usando GET /2/webhooks.
Testes com xurl
Para fins de teste, a ferramentaxurl suporta webhooks temporários. Instale a versão mais recente do projeto xurl do GitHub, configure sua autorização e depois execute:
Notas importantes
Apps de exemplo
Próximos passos
Filtered Stream Webhooks
Receba Posts filtrados via webhook
Account Activity API
Receba eventos de conta via webhook