Pular para o conteúdo principal
Este guia explica como assinar e receber eventos usando os endpoints da X Activity API. Geralmente, há três etapas envolvidas:
  1. Identificar o User ID do usuário cujos eventos você deseja filtrar
  2. Criar uma assinatura para o tipo de evento que você deseja filtrar para esse usuário
  3. Receber os eventos usando webhook ou uma conexão HTTP persistente (stream)

​
Obtendo IDs de usuário

Antes de criar assinaturas, você precisará saber o ID de usuário da conta que deseja filtrar. Neste exemplo, usaremos o handle XDevelopers. Você pode consultar IDs de usuário de algumas maneiras, incluindo: Consultar o ID de um usuário pelo nome de usuário: 
curl -H "Authorization: Bearer SEU_BEARER_TOKEN" "https://api.x.com/2/users/by/username/xdevelopers"
Obtenha seu próprio id de usuário: 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" https://api.x.com/2/users/me
Ambos os endpoints retornam informações do usuário, incluindo o campo id, que você pode usar em filtros de assinatura. Um exemplo de resposta JSON é exibido abaixo: 
{
    "data": {
        "id": "2244994945",
        "name": "Developers",
        "username": "XDevelopers"
    }
}

​
Criando uma assinatura

O próximo passo é criar uma assinatura. Neste exemplo, vamos assinar as atualizações da bio do XDevelopers. Para isso, passaremos user_id e event_type no corpo do JSON. Neste caso, o event_type é ProfileBioUpdate. Vamos informar o user ID do X Developer: 2244994945 e uma tag opcional: 
{
  "event_type": "ProfileBioUpdate",
  "filter": {
    "user_id": "2244994945"
  },
  "tag": "atualizações de bio de Xdevelopers"
}
Usaremos nosso Token do tipo Bearer (obtido no portal do desenvolvedor) para autorização em todos os endpoints relacionados ao XAA: 
curl -H "Authorization: Bearer SEU_BEARER_TOKEN" \
  https://api.x.com/2/activity/subscriptions \
  -X POST \
  -d '{
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "2244994945"
    },
    "tag": "atualizações de bio do Xdevelopers"
  }'
Com uma solicitação bem-sucedida, sua assinatura será criada: 
{
  "data":[
    {
      "created_at":"2025-10-09T16:35:08.000Z",
      "event_type":"ProfileBioUpdate",
      "filter":{
        "user_id":"2244994945"
      },
      "subscription_id":"1976325569252868096",
      "tag": "atualizações de bio dos Xdevelopers",
      "updated_at":"2025-10-09T16:35:08.000Z"
    }
  ],
  "meta": {
    "total_subscriptions": 1
  }
}

​
Obtendo os eventos

Depois de criarmos a assinatura, podemos receber os eventos por meio de webhooks ou de um stream HTTP persistente. Neste exemplo, abriremos o stream HTTP persistente: 
curl -H "Authorization: Bearer SEU_TOKEN_DE_BEARER" https://api.x.com/2/activity/stream
Quando a conta Xdevelopers atualizar sua biografia de perfil, o evento será entregue pelo fluxo: 
{
  "data": {
    "filter": {
      "user_id": "2244994945"
    },
    "event_type": "ProfileBioUpdate",
    "tag": "Atualizações de bio de Xdevelopers",
    "payload": {
      "before": "Marte e Carros",
      "after": "Marte, Carros e IA"
    }
  }
}

​
Gerenciamento de assinaturas

A X Activity API oferece endpoints para gerenciar suas assinaturas por meio de operações CRUD padrão.

​
Criar assinatura

Crie uma nova assinatura para receber eventos: 
curl -H "Authorization: Bearer SEU_BEARER_TOKEN" \
  -X POST \
  https://api.x.com/2/activity/subscriptions \
  -d '{
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "123456789"
    },
    "tag": "minhas atualizações de bio",
    "webhook_id": "1976325569252868099"
  }'
Observação:
  • O campo tag é opcional. Ele pode ser usado para ajudar a identificar eventos durante a entrega.
  • O campo webhook_id também é opcional. Consulte nossa documentação de webhooks para obter ajuda na configuração de um webhook. Se um webhook_id for especificado, o evento será entregue ao webhook informado, além do stream, se ele estiver aberto.
Resposta: 
{
  "data": {
    "subscription_id": "1976325569252868096",
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "123456789"
    },
    "created_at": "2025-10-09T16:35:08.000Z",
    "updated_at": "2025-10-09T16:35:08.000Z",
    "tag": "minhas atualizações de bio",
    "webhook_id": "1976325569252868099"
  }
}

​
Listar assinaturas

Recupere todas as assinaturas ativas do seu app: 
curl -H "Authorization: Bearer SEU_TOKEN_DE_BEARER" \
  https://api.x.com/2/activity/subscriptions
Resposta: 
{
  "data": [
    {
      "subscription_id": "1976325569252868096",
      "event_type": "AtualizacaoDaBioDoPerfil",
      "filter": {
        "user_id": "123456789"
      },
      "created_at": "2025-10-09T16:35:08.000Z",
      "updated_at": "2025-10-10T03:50:59.000Z",
    },
    {
      "subscription_id": "1976325569252868097",
      "event_type": "AtualizacaoDaFotoDoPerfil",
      "filter": {
        "user_id": "987654321"
      },
      "created_at": "2025-10-08T14:35:08.000Z",
      "updated_at": "2025-10-08T14:35:08.000Z",
    }
  ],
  "meta": {
    "total_subscriptions": 2
  }
}

​
Excluir assinatura

Remover uma assinatura: 
curl -H "Authorization: Bearer SEU_TOKEN_DE_BEARER" \
  -X DELETE \
  https://api.x.com/2/activity/subscriptions/1976325569252868096
Resposta: 
{
  "data": {
    "deleted": true
  },
  "meta": {
    "total_subscriptions": 0
  }
}
total_subscriptions indica a quantidade restante de assinaturas associadas ao seu app após a operação de exclusão.

​
Atualizar assinatura

O endpoint PUT permite atualizar o método de entrega ou a tag de uma assinatura. Atualizar o filter ou o event_type requer excluir a assinatura existente e adicionar uma nova. 
curl -H "Authorization: Bearer SEU_TOKEN_DE ACESSO" \
  -X PUT \
  https://api.x.com/2/activity/subscriptions/1976325569252868096 \
  -d '{
    "tag": "meu novo marcador",
    "webhook_id": "192846273860294839"
  }'
Resposta: 
{
  "data": {
    "subscription_id": "1976325569252868096",
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "123456789"
    },
    "created_at": "2025-10-09T16:35:08.000Z",
    "updated_at": "2025-10-10T17:10:58.000Z",
    "tag": "minha nova tag",
    "webhook_id": "192846273860294839"
  },
  "meta": {
    "total_subscriptions": 1
  }
}