Introduction

​

Webhooks API v2

​

Visão geral

A API de Webhooks v2 permite que desenvolvedores recebam notificações de eventos em tempo real de contas do X por meio de mensagens JSON enviadas via webhook. Essa API permite registrar e gerenciar webhooks, desenvolver aplicativos consumidores para processar eventos e garantir uma comunicação segura por meio de verificações de desafio-resposta (CRC) e cabeçalhos de assinatura.

​

Resumo dos recursos

Nível	Preço	Número de webhooks
Self-Serve Pro	US$ 5.000/mês	1
Enterprise	Fale com vendas	5+

​

Produtos que oferecem suporte a webhooks

Estes são os produtos que atualmente oferecem a entrega de eventos via webhook:

• Account Activity API (AAA)
• Filtered Stream

​

Gerenciar webhooks

A Account Activity API fornece mensagens JSON baseadas em webhook sempre que houver eventos associados a contas do X inscritas no seu serviço. O X entrega essas atividades ao seu webhook registrado. Nas etapas a seguir, você aprenderá a gerenciar webhooks e usuários inscritos.

Você aprenderá a registrar, visualizar e remover tanto webhooks quanto usuários inscritos. Usaremos comandos simples do cURL para fazer solicitações aos diversos endpoints da API. O cURL é uma ferramenta de linha de comando para enviar ou obter solicitações usando a sintaxe de URL.

Há vários detalhes que exigem atenção antes que você possa começar a receber eventos de webhook no seu aplicativo consumidor de eventos. Como descrito abaixo, você precisará criar um X App, obter acesso à Account Activity API e desenvolver um aplicativo web que consuma eventos de webhook. 

​

1. Desenvolva um App consumidor de webhook

Para registrar um novo webhook associado à sua X App, você precisará desenvolver, implantar e hospedar um app web que receba eventos de webhook da X e responda às nossas solicitações de segurança.

Antes de começar, recomendamos conferir nossos apps de exemplo!

• Crie um app web com uma URL HTTPS publicamente acessível que atuará como o endpoint do webhook para receber eventos. 
  • O path da URI fica a seu critério. Este exemplo seria válido: https://mydomain.com/service/listen
  • Se você estiver recebendo webhooks de várias fontes, um padrão comum é: https://mydomain.com/webhook/twitter
  • Observe que a URL especificada não pode incluir uma porta (https://mydomain.com:5000/NoWorkie).
• Um primeiro passo é escrever código que receba uma solicitação GET de X Challenge Response Check (CRC) e responda com um JSON devidamente formatado. 
• Registre sua URL de webhook. Você fará uma solicitação POST para o endpoint /2/webhooks com a URL no corpo JSON. Ao fazer essa solicitação, a X enviará uma solicitação CRC para seu app web.
• Quando um webhook é registrado com sucesso, a resposta incluirá um webhook id. Esse webhook id será necessário posteriormente ao fazer solicitações para produtos que oferecem suporte a webhooks. 
• A X enviará solicitações POST contendo eventos para a URL que você registrou. Esses eventos serão codificados em JSON. Veja aqui exemplos de payloads JSON de webhook.

​

Opcional: use o xurl para testes

Para fins de teste, a ferramenta xurl agora oferece suporte a webhooks temporários! Instale a versão mais recente do projeto xurl no GitHub, configure sua autorização e, em seguida, execute:

xurl webhook start

Isso gerará uma URL pública temporária de webhook, tratará automaticamente todas as verificações de CRC e registrará quaisquer eventos de assinatura recebidos. É uma ótima maneira de validar sua configuração antes de implantar. Exemplo de saída:

Iniciando servidor de webhook com ngrok...
Digite seu authtoken do ngrok (deixe vazio para tentar a variável de ambiente NGROK_AUTHTOKEN):

Tentando usar a variável de ambiente NGROK_AUTHTOKEN para autenticação do ngrok.
Configurando ngrok para encaminhar para a porta local: 8080
Túnel ngrok estabelecido!
  URL de encaminhamento: https://<your-ngrok-subdomain>.ngrok-free.app -> localhost:8080

Use esta URL para o registro do seu webhook da X API: https://<your-ngrok-subdomain>.ngrok-free.app/webhook

Iniciando servidor HTTP local para processar requisições do túnel ngrok (encaminhadas de https://<your-ngrok-subdomain>.ngrok-free.app)...

Notas importantes

• Ao registrar a URL do seu webhook, seu app web precisa usar o consumer secret do seu App para criptografar a verificação CRC.

• Todas as Mensagens diretas recebidas serão entregues via webhooks. Todas as Mensagens diretas enviadas via POST /2/dm_conversations/with/:participant_id/messages também serão entregues via webhooks. Isso permite que seu app web tenha ciência de Mensagens diretas enviadas por um cliente diferente.

• Se você tiver mais de um app web compartilhando a mesma URL de webhook e o mesmo usuário mapeado para cada app, o mesmo evento será enviado ao seu webhook várias vezes (uma por app web).

• Em alguns casos, seu webhook pode receber eventos duplicados. Seu app de webhook deve ser tolerante a isso e realizar deduplicação pelo id do evento.

• Consulte o código de exemplo:

  • Account Activity API Setup, um app web em Node que exibe eventos de webhook usando o nível Enterprise da Account Activity API.

​

2. Protegendo webhooks

As APIs baseadas em webhook da X oferecem dois métodos para confirmar a segurança do seu servidor de webhook:

1. As verificações de desafio–resposta permitem que a X confirme a propriedade do app web que recebe eventos de webhook.
2. O cabeçalho de assinatura em cada solicitação POST permite que você confirme que a X é a origem dos webhooks recebidos.

Consulte a seção Verificação de CRC para os requisitos de implementação.

​

3. A API de Webhooks

Webhooks são gerenciados por meio da Webhook Management API. Todos os endpoints exigem autenticação OAuth 2.0 App only com Bearer Token.

​

Adicionando um webhook

POST /2/webhooks

Descrição:

Crie uma configuração de webhook. Sua URL de callback https, publicamente acessível, deve ser fornecida no corpo JSON.
Vamos começar registrando uma nova URL de webhook para o contexto de aplicação informado.

Autenticação:

OAuth2 App only Bearer Token

• Bearer token <BEARER_TOKEN> por exemplo: AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

Parâmetros (corpo JSON):

{
    "url": "<sua URL de callback https publicamente acessível>"
}

• URL <URL> por exemplo: https://yourdomain.com/webhooks/twitter/

Request: Copie o seguinte comando cURL no seu terminal após fazer as alterações a seguir:

  ```
  curl --request POST --url 'https://api.twitter.com/2/webhooks?url=<URL>' --header 'authorization: Bearer <BEARER_TOKEN>'
  --data '{
"url": "https://yourdomain.com/webhooks/twitter"
          }'
  ```

Respostas:

Sucesso (200 OK)

Uma resposta bem-sucedida indica que o webhook foi criado e que a verificação CRC inicial foi concluída com êxito.

{
  "data": {
    "id": "<webhook_id>",
    "url": "<sua URL de callback>",
    "valid": true,
    "created_at": "YYYY-mm-DDTHH:MM:ss.000Z"
  }
}

Falha (400 Bad Request)

Falhas retornam um objeto de erro padrão.

{
    "errors": [
      {
        "message": "<Motivo>: <Detalhes>"
      }
    ],
    "title": "Solicitação Inválida",
    "detail": "Um ou mais parâmetros da sua solicitação são inválidos.",
    "type": "https://api.twitter.com/2/problems/invalid-request"
}

Motivos comuns de falha incluem:

Motivo	Descrição
CrcValidationFailed	A URL de callback não respondeu corretamente à verificação de CRC (por exemplo, ocorreu timeout, resposta incorreta).
UrlValidationFailed	A URL de callback fornecida não atende aos requisitos (por exemplo, não é https, formato inválido).
DuplicateUrlFailed	Já existe um webhook registrado pela sua App para a URL de callback fornecida.
WebhookLimitExceeded	Sua App atingiu o número máximo permitido de configurações de webhook.

​

Visualizando um webhook

GET /2/webhooks

Descrição: Recupere todas as configurações de webhook associadas ao seu App (conta de desenvolvedor).

Autenticação:

OAuth2 App only Bearer Token

• Bearer token <BEARER_TOKEN> por exemplo, AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

• URL <URL> por exemplo, https://yourdomain.com/webhooks/twitter/

Solicitação: Execute o comando a seguir para obter todas as URLs de webhook registradas e seus statuses para o App informado.

Copie a seguinte requisição cURL no seu terminal após fazer as seguintes alterações:

  ```
  curl --request GET --url 'https://api.twitter.com/2/webhooks' --header 'authorization: Bearer <BEARER_TOKEN>'
  ```

Sucesso (200 OK)

Retorna uma lista de configurações de webhook. A lista estará vazia se nenhum webhook estiver configurado.

Exemplo (com um webhook configurado):

{
  "data": [
    {
      "created_at": "YYYY-mm-DDTHH:MM:ss.000Z",
      "id": "<webhook_id>",
      "url": "<callback url>",
      "valid": true
    }
  ],
  "meta": {
    "result_count": 1
  }
}

Exemplo (sem webhooks configurados):

{
  "data": [],
  "meta": {
    "result_count": 0
  }
}

​

Removendo um webhook

DELETE /2/webhooks/:webhook_id

Descrição: Exclua uma configuração de webhook usando seu webhook_id específico. O id pode ser obtido na resposta de criação do POST /2/webhooks ou na resposta de listagem do GET /2/webhooks.

Autenticação:

OAuth2 App only Bearer Token

• Bearer token <BEARER_TOKEN> por exemplo: AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

Parâmetros de caminho:

Parâmetro	Descrição
webhook_id	O id do webhook a ser excluído.

Requisição: Execute o seguinte comando para remover o webhook da configuração da App fornecida.

Copie a solicitação cURL a seguir no seu terminal após fazer as seguintes alterações:

  ```
  curl --request DELETE --url 'https://api.twitter.com/2/webhooks/:WEBHOOK_ID' --header 'authorization: Bearer <BEARER_TOKEN>'
  ```

  **Respostas:**

Sucesso (200 OK)

Retorna uma resposta JSON com o status “deleted” definido como true se a exclusão for bem-sucedida.

Exemplo (com exclusão bem-sucedida do webhook):

{
  "data": {
    "deleted": true
  }
}

Falha (400 Bad Request)

Motivo	Descrição
WebhookIdInvalid	O webhook_id fornecido não foi encontrado ou não está associado à sua App.

​

Validar e reativar webhook

PUT /2/webhooks/:webhook_id

Descrição: Aciona a verificação de resposta ao desafio (CRC) para a URL do webhook informado. Se a verificação for bem-sucedida, retorna 200 e reativa o webhook definindo seu status como valid.

Autenticação:

OAuth2 App only Bearer Token

• Bearer Token <BEARER_TOKEN> por exemplo, AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

Parâmetros de caminho:

Parâmetro	Descrição
webhook_id	O id do webhook a ser validado.

Solicitação: Execute o seguinte comando para validar o webhook com base na configuração do App fornecido.

Copie a seguinte solicitação cURL no seu terminal após fazer as seguintes alterações:

  ```
  curl --request PUT --url 'https://api.twitter.com/2/webhooks/:WEBHOOK_ID' --header 'authorization: Bearer <BEARER_TOKEN>'
  ```

  **Respostas:**

Sucesso (200 OK)

Uma resposta 200 OK indica que a solicitação de verificação CRC foi iniciada. Ela não garante que a verificação CRC foi aprovada. O campo valid na resposta reflete o status após a tentativa de verificação. Se a verificação CRC for bem-sucedida, o status do webhook será atualizado para válido. Você pode verificar o status atual usando GET /2/webhooks.

{
  "data": {
    "valid": true // Indica o status após a conclusão da tentativa de verificação CRC
  }
}

Falha (400 Solicitação Inválida)

Motivo	Descrição
WebhookIdInvalid	O webhook_id fornecido não foi encontrado ou não está associado ao seu App.
CrcValidationFailed	A URL de retorno de chamada não respondeu corretamente à solicitação de verificação de CRC.

​

4. A verificação CRC

O Challenge Response Check (CRC) é como a X valida se a URL de callback fornecida é válida e está sob seu controle.

Quando o CRC é acionado:

• No registro inicial do webhook (POST /2/webhooks)
• A cada hora pela X para validação
• Manualmente via PUT /2/webhooks/:id

Exemplo:

GET https://your-webhook-url.com/webhook?crc_token=challenge_string

Exemplo de corpo de resposta em JSON:

{
  "response_token": "sha256=<base64_encoded_hmac_hash>"
}

Como gerar a resposta:

• Use crc_token como a mensagem
• Use o consumer secret do App como a chave
• Gere um hash HMAC SHA-256
• Codifique o resultado em Base64

​

Apps de exemplo

• Servidor de webhook simples
  • Um único script em Python que mostra como responder à verificação de CRC e aceitar eventos POST.
• Painel de exemplo da Account Activity API
  • Um app web desenvolvido com bun.sh que permite gerenciar webhooks, assinaturas e receber eventos em tempo real diretamente no app.