Skip to main content
Este guia orienta você na configuração de um app consumidor de webhook, na implementação do Challenge-Response Check (CRC), na proteção de eventos recebidos e no registro do seu webhook no X.

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/listen
    • https://mydomain.com/webhook/twitter
  • A URL não pode incluir uma especificação de porta (por exemplo, https://mydomain.com:5000/webhook nã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 consulta crc_token:
Sua aplicação deve responder com um corpo JSON contendo um response_token:

Como construir a resposta do CRC

  1. Use o valor de crc_token do parâmetro de consulta como a mensagem
  2. Use o consumer secret (API secret key) do seu app como a chave
  3. Crie um hash HMAC SHA-256
  4. Faça o Base64 encode do resultado
  5. Adicione sha256= como prefixo à string codificada
Importante: Seu web app deve usar o consumer secret (API secret key) do seu app para a criptografia CRC — não seu bearer token ou access token.

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 header x-twitter-webhooks-signature que permite confirmar que o X é a origem do webhook recebido. Para verificar a assinatura:
  1. Obtenha o valor do header x-twitter-webhooks-signature da requisição recebida
  2. Crie um hash HMAC SHA-256 usando seu consumer secret como chave e o corpo bruto da requisição como mensagem
  3. Faça o Base64 encode do hash e adicione sha256= como prefixo
  4. 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ção POST /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/webhooksReferência da API
Resposta de sucesso (200 OK): Uma resposta bem-sucedida indica que o webhook foi criado e que o CRC check inicial passou.
Quando um webhook é registrado com sucesso, a resposta inclui um webhook ID. Esse ID é necessário ao fazer requisições a produtos que suportam webhooks (por exemplo, vincular ao Filtered Stream ou criar subscriptions para o Account Activity). Motivos comuns de falha:

Visualizar webhooks

GET /2/webhooksReferência da API Recupere todas as configurações de webhook associadas à sua aplicação.
Resposta (com um webhook):
Exemplo de resposta
Resposta (sem webhooks):

Excluir um webhook

DELETE /2/webhooks/:webhook_idReferência da API Exclua um webhook usando seu webhook_id (obtido na resposta de criação ou listagem).
Resposta:

Validar e reativar um webhook

PUT /2/webhooks/:webhook_idReferência da API Aciona um CRC check para o webhook informado. Se o check for bem-sucedido, o webhook é reativado com valid: true.
Resposta: Uma resposta 200 OK indica que o CRC check foi iniciado. O campo 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 ferramenta xurl suporta webhooks temporários. Instale a versão mais recente do projeto xurl do GitHub, configure sua autorização e depois execute:
Isso gerará uma URL de webhook pública temporária, lidará automaticamente com todos os CRC checks e registrará quaisquer eventos de subscription recebidos. É uma ótima maneira de verificar sua configuração antes de fazer o deploy. Exemplo de saída:

Notas importantes

  • Todas as Direct Messages recebidas serão entregues via webhooks. DMs enviadas via POST /2/dm_conversations/with/:participant_id/messages também serão entregues, para que seu app possa acompanhar DMs enviadas por outros clientes.
  • Se você tiver mais de um web app compartilhando a mesma URL de webhook e o mesmo usuário mapeado para cada app, o mesmo evento será enviado para o seu webhook várias vezes (uma por web app).
  • Em alguns casos, seu webhook pode receber eventos duplicados. Seu app de webhook deve tolerar isso e desduplicar pelo ID do evento.
  • O X envia eventos como requisições POST com payloads JSON. Consulte a estrutura do objeto de dados do Account Activity para exemplos de payloads.

Apps de exemplo


Próximos passos

Filtered Stream Webhooks

Receba Posts filtrados via webhook

Account Activity API

Receba eventos de conta via webhook