Saltar al contenido principal
Esta guía explica cómo suscribirse y recibir eventos mediante los puntos de conexión de la X Activity API. Por lo general, hay 3 pasos:
  1. Identificar el User ID del usuario cuyos eventos desea filtrar
  2. Crear una suscripción para el tipo de evento que desea filtrar para ese usuario
  3. Recibir los eventos mediante un webhook o una conexión HTTP persistente (stream)

​
Obtención de IDs de usuario

Antes de crear suscripciones, necesitarás conocer el id de usuario de la cuenta que quieres filtrar. En este ejemplo, usaremos el handle de XDevelopers. Puedes buscar IDs de usuario de varias formas, entre ellas: Buscar el id de un usuario por nombre de usuario: 
curl -H "Authorization: Bearer TU_TOKEN_DE_PORTADOR" "https://api.x.com/2/users/by/username/xdevelopers"
Obtén tu propio id de usuario: 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" https://api.x.com/2/users/me
Ambos puntos de conexión devuelven información de usuario, incluido el campo id, que puede utilizar en filtros de suscripción. A continuación se muestra un ejemplo de respuesta JSON: 
{
    "data": {
        "id": "2244994945",
        "name": "Developers",
        "username": "XDevelopers"
    }
}

​
Creación de una suscripción

El siguiente paso es crear una suscripción. En este ejemplo, nos suscribiremos a las actualizaciones de la biografía de XDevelopers. Para ello, incluiremos user_id y event_type en el cuerpo JSON. En este caso, el event_type es ProfileBioUpdate. Usaremos el ID de usuario de X Developer: 2244994945, y una etiqueta opcional: 
{
  "event_type": "ProfileBioUpdate",
  "filter": {
    "user_id": "2244994945"
  },
  "tag": "Actualizaciones de la biografía de Xdevelopers"
}
Usaremos nuestro Token Bearer (del portal para desarrolladores) para la autorización en todos los puntos de conexión relacionados con XAA: 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  https://api.x.com/2/activity/subscriptions \
  -X POST \
  -d '{
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "2244994945"
    },
    "tag": "Actualizaciones de la biografía de Xdevelopers"
  }'
Si la solicitud se procesa correctamente, se creará la suscripción: 
{
  "data":[
    {
      "created_at":"2025-10-09T16:35:08.000Z",
      "event_type":"ProfileBioUpdate",
      "filter":{
        "user_id":"2244994945"
      },
      "subscription_id":"1976325569252868096",
      "tag": "Actualizaciones de la biografía de Xdevelopers",
      "updated_at":"2025-10-09T16:35:08.000Z"
    }
  ],
  "meta": {
    "total_subscriptions": 1
  }
}

​
Obtención de eventos

Una vez creada la suscripción, podemos recibir los eventos mediante webhooks o un flujo HTTP persistente. En este ejemplo, abriremos el flujo HTTP persistente: 
curl -H "Authorization: Bearer TU_BEARER_TOKEN" https://api.x.com/2/activity/stream
Cuando la cuenta de Xdevelopers actualice su biografía de perfil, el evento se entregará a través del flujo: 
{
  "data": {
    "filter": {
      "user_id": "2244994945"
    },
    "event_type": "ProfileBioUpdate",
    "tag": "Actualizaciones de biografía de Xdevelopers",
    "payload": {
      "before": "Mars & Cars",
      "after": "Mars, Cars & AI"
    }
  }
}

​
Gestión de suscripciones

La API de X Activity ofrece puntos de conexión para administrar tus suscripciones mediante operaciones CRUD estándar.

​
Crear una suscripción

Cree una nueva suscripción para recibir eventos: 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X POST \
  https://api.x.com/2/activity/subscriptions \
  -d '{
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "123456789"
    },
    "tag": "actualizaciones de mi biografía",
    "webhook_id": "1976325569252868099"
  }'
Nota:
  • El campo tag es opcional. Puede utilizarse para ayudar a identificar eventos durante la entrega.
  • El campo webhook_id también es opcional. Consulta nuestra documentación de webhooks para obtener ayuda para configurar un webhook. Si se especifica un webhook_id, el evento se entregará al webhook indicado, además del flujo si está abierto.
Respuesta: 
{
  "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": "actualizaciones de mi biografía",
    "webhook_id": "1976325569252868099"
  }
}

​
Listar suscripciones

Obtén todas las suscripciones activas de tu aplicación: 
curl -H "Authorization: Bearer TU_TOKEN_DE_PORTADOR" \
  https://api.x.com/2/activity/subscriptions
Respuesta: 
{
  "data": [
    {
      "subscription_id": "1976325569252868096",
      "event_type": "ProfileBioUpdate",
      "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": "ProfilePictureUpdate",
      "filter": {
        "user_id": "987654321"
      },
      "created_at": "2025-10-08T14:35:08.000Z",
      "updated_at": "2025-10-08T14:35:08.000Z",
    }
  ],
  "meta": {
    "total_subscriptions": 2
  }
}

​
Eliminar suscripción

Elimina una suscripción: 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X DELETE \
  https://api.x.com/2/activity/subscriptions/1976325569252868096
Respuesta: 
{
  "data": {
    "deleted": true
  },
  "meta": {
    "total_subscriptions": 0
  }
}
total_subscriptions muestra el número restante de suscripciones asociadas a tu aplicación después de la operación de eliminación.

​
Actualizar la suscripción

El punto de conexión PUT permite actualizar el método de entrega o la etiqueta de una suscripción. Actualizar filter o event_type requiere eliminar la suscripción existente y crear una nueva. 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X PUT \
  https://api.x.com/2/activity/subscriptions/1976325569252868096 \
  -d '{
    "tag": "my new tag",
    "webhook_id": "192846273860294839"
  }'
Respuesta: 
{
  "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": "my new tag",
    "webhook_id": "192846273860294839"
  },
  "meta": {
    "total_subscriptions": 1
  }
}