Inicio rápido

​

Introducción a la API de webhooks de stream filtrado

La API v2 de webhooks de stream filtrado es similar al endpoint v2 de stream filtrado en cuanto a la configuración de las reglas de filtrado. La diferencia está en el mecanismo de entrega de las Publicaciones que coinciden con tus reglas.

• En el caso del endpoint v2 de stream filtrado, tienes que establecer una conexión persistente y escuchar las Publicaciones que coincidan con tus reglas.
• En el caso de este endpoint de webhook de stream filtrado, registras tu webhook y X entrega las Publicaciones que coinciden con tus reglas a tu webhook.

Esta guía explica cómo filtrar y recibir Publicaciones usando los endpoints de webhooks de stream filtrado. Este proceso consta de 3 pasos:

1. Configurar tus reglas de stream filtrado
2. Crear tu webhook
3. Vincular tu instancia de Filtered Stream con tu webhook

Una vez que hayas vinculado tu instancia de Filtered Stream con tu webhook, X enviará las Publicaciones que coincidan con tus reglas a tu webhook.

​

Configurar tus reglas de flujo filtrado

Las reglas de flujo filtrado se componen de uno o varios operadores que se combinan usando lógica booleana y paréntesis para definir qué Publicaciones se enviarán a tus webhooks. La API de webhooks de flujo filtrado utiliza el mismo conjunto de endpoints que el endpoint de flujo filtrado v2 para crear y gestionar reglas. Consulta esta guía detallada que muestra cómo puedes crear filtros.

​

Creación de tu webhook

Crea un webhook para recibir eventos registrando una URL HTTPS accesible públicamente en la X API. Los webhooks deben manejar solicitudes GET para la validación CRC y solicitudes POST para los payloads de eventos. Sigue la documentación de introducción a Webhooks para consultar los pasos detallados sobre cómo crear y administrar webhooks.

Nota: Si ya usas webhooks para la Account Activity API (AAA), los webhooks que configuraste para esa API funcionan exactamente igual aquí. De hecho, puedes usar el mismo endpoint de webhook que usas para AAA en esta API, si cuentas con el ancho de banda y puedes separar los eventos.

​

Vincular tu instancia de Filtered Stream a tu webhook

Una vez que tengas configuradas tus reglas y creado el webhook, vincula el webhook a tu instancia de Filtered Stream. Esto redirige los eventos de Publicaciones coincidentes a la URL de tu webhook.

Usa el endpoint: POST /2/tweets/search/webhooks/:webhook_id

Puedes incluir parámetros de consulta idénticos a los utilizados en el endpoint de streaming /2/tweets/search/stream, como expansions, campos y opciones de medios. Esto personaliza los datos incluidos en las cargas útiles de eventos.

Ejemplo:

curl --request POST \ 
  --url 
'https://api.x.com/2/tweets/search/webhooks/123456789012345678?ex
pansions=author_id&user.fields=username,name,id' \ 
  --header 'Authorization: Bearer $BEARER_TOKEN' 

Ejemplo de respuesta exitosa:

{ 
  "data": { 
    "provisioned": true 
  } 
}

Consejo: Puedes vincular varios webhooks al mismo stream para lograr redundancia o para recibir distintos conjuntos de campos. Cada enlace puede especificar parámetros únicos.

Una vez que conectes tu instancia de Filtered Stream a tu webhook, empezarás a recibir Publicaciones que coincidan con tus reglas, como se muestra a continuación:

{
    "data": {
        "id": "1346889436626259968",
        "text": "Learn how to use the user Post timeline and user mention timeline endpoints in the X API v2 to explore Post… https://t.co/56a0vZUx7i",
        "created_at": "2021-01-06T18:40:40.000Z",
        "author_id": "2244994945"
    },
    "includes": {
        "users": [
            {
                "id": "2244994945",
                "name": "Developers",
                "username": "Xdevelopers",
                "created_at": "2013-12-14T04:35:55Z",
                "protected": false
            }
        ]
    },
    "matching_rules": [
        {
            "id": "120897978112909812",
            "tag": "api-posts"
        }
    ]
}

​

Obtención de webhooks vinculados a Filtered Stream

Obtén una lista de todos los webhooks que están vinculados actualmente a tu Filtered Stream:

GET /2/tweets/search/stream/webhooks 

Ejemplo de respuesta:

{
    "data": {
        "links": [
            {
                "application_id": "29893711",
                "business_user_id": "1877374016438091776",
                "fields": [
                    "user.fields=username",
                    "name",
                    "id",
                    "expansions=author_id"
                ],
                "instance_id": "1877375130462289920",
                "webhook_id": "1952390923729424384"
            }
        ]
    }
}

​

Desvincular tu webhook de Filtered Stream

Para dejar de recibir eventos en un webhook específico, desvincúlalo con:

DELETE /2/tweets/search/webhooks/:webhook_id

La respuesta será la siguiente:

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