Introduction

​

API de Webhooks v2

​

Descripción general

La API de Webhooks v2 permite a los desarrolladores recibir notificaciones de eventos en tiempo real de cuentas de X mediante mensajes JSON basados en webhooks. Esta API le permite registrar y administrar webhooks, desarrollar aplicaciones consumidoras para procesar eventos y garantizar una comunicación segura mediante verificaciones de desafío-respuesta (CRC) y encabezados de firma.

​

Resumen de funcionalidades

Nivel	Precio	Número de webhooks
Pro de autoservicio	5.000 $/mes	1
Empresarial	Contactar con ventas	5+

​

Productos que admiten webhooks

Estos son los productos que actualmente admiten la entrega de eventos mediante webhooks:

• Account Activity API (AAA)
• Filtered Stream

​

Administrar webhooks

La Account Activity API te proporciona mensajes JSON basados en webhooks cada vez que hay eventos asociados a cuentas de X suscritas a tu servicio. X entrega esas actividades a tu webhook registrado. En los siguientes pasos, aprenderás a administrar webhooks y usuarios suscritos.

Aprenderás a registrar, ver y eliminar tanto webhooks como usuarios suscritos. Usaremos comandos simples de cURL para realizar solicitudes a los distintos endpoints de la API. cURL es una herramienta de línea de comandos para realizar o enviar solicitudes utilizando la sintaxis de URL.

Hay varios detalles que requieren atención antes de que puedas empezar a recibir eventos de webhook en tu aplicación consumidora de eventos. Como se describe a continuación, necesitarás crear una App de X, obtener acceso a la Account Activity API y desarrollar una aplicación web que consuma eventos de webhook. 

​

1. Desarrolle una App consumidora de webhooks

Para registrar un nuevo webhook asociado con su App de X, deberá desarrollar, implementar y alojar una aplicación web que reciba eventos de webhook de X y responda a nuestras solicitudes de seguridad.

Antes de comenzar, le recomendamos consultar nuestras aplicaciones de ejemplo!

• Cree una aplicación web con una URL HTTPS de acceso público que actuará como el endpoint del webhook para recibir eventos.
  • La ruta del URI queda completamente a su criterio. Este ejemplo sería válido: https://mydomain.com/service/listen
  • Si va a recibir webhooks de diversas fuentes, un patrón común es: https://mydomain.com/webhook/twitter
  • Tenga en cuenta que la URL especificada no puede incluir una especificación de puerto (https://mydomain.com:5000/NoWorkie).
• Un primer paso es escribir código que reciba una solicitud GET de X Challenge Response Check (CRC) y responda con un JSON correctamente formateado.
• Registre la URL de su webhook. Hará una solicitud POST al endpoint /2/webhooks con la URL en el cuerpo JSON. Cuando realice esta solicitud, X enviará una solicitud CRC a su aplicación web.
• Cuando un webhook se registre correctamente, la respuesta incluirá un id de webhook. Este id de webhook se necesitará más adelante al realizar solicitudes a productos que admiten webhooks.
• X enviará solicitudes POST con eventos a la URL que registró. Estos eventos estarán codificados en JSON. Consulte aquí ejemplos de cargas útiles JSON de webhooks.

​

Opcional: Usa xurl para pruebas

Con fines de prueba, la herramienta xurl ahora admite webhooks temporales. Instala la versión más reciente del proyecto xurl desde GitHub, configura tu autorización y luego ejecuta:

xurl webhook start

Esto generará una URL pública temporal de webhook, manejará automáticamente todas las comprobaciones CRC y registrará cualquier evento de suscripción entrante. Es una excelente forma de verificar tu configuración antes del despliegue. Ejemplo de salida:

Iniciando servidor de webhook con ngrok...
Ingrese su authtoken de ngrok (deje vacío para intentar usar la variable de entorno NGROK_AUTHTOKEN):

Intentando usar la variable de entorno NGROK_AUTHTOKEN para la autenticación de ngrok.
Configurando ngrok para reenviar al puerto local: 8080
¡Túnel de ngrok establecido!
  URL de reenvío: https://<your-ngrok-subdomain>.ngrok-free.app -> localhost:8080

Utilice esta URL para el registro de webhook de X API: https://<your-ngrok-subdomain>.ngrok-free.app/webhook

Iniciando servidor HTTP local para gestionar solicitudes del túnel de ngrok (reenviadas desde https://<your-ngrok-subdomain>.ngrok-free.app)...

Notas importantes

• Al registrar tu URL de webhook, tu app web debe usar el consumer secret de tu App para cifrar la verificación CRC.

• Todos los Mensajes Directos entrantes se entregarán mediante webhooks. Todos los Mensajes Directos enviados con POST /2/dm_conversations/with/:participant_id/messages también se entregarán mediante webhooks. Esto permite que tu app web detecte Mensajes Directos enviados desde otro cliente.

• Si tienes más de una app web que comparte la misma URL de webhook y el mismo usuario asignado a cada App, el mismo evento se enviará a tu webhook varias veces (una por cada app web).

• En algunos casos, tu webhook puede recibir eventos duplicados. Tu app de webhook debe tolerarlo y eliminar duplicados por id de evento.

• Consulta el código de ejemplo:

  • Account Activity API Setup, una app web de Node que muestra eventos de webhook utilizando el plan Empresarial de la Account Activity API.

​

2. Protección de webhooks

Las APIs basadas en webhooks de X proporcionan dos métodos para confirmar la seguridad de su servidor de webhook:

1. Las comprobaciones de desafío-respuesta permiten a X confirmar la propiedad de la aplicación web que recibe eventos de webhook.
2. El encabezado de firma en cada solicitud POST le permite confirmar que X es el origen de los webhooks entrantes.

Consulte la sección Comprobación CRC para los requisitos de implementación.

​

3. La API de Webhooks

Los webhooks se gestionan a través de la Webhook Management API. Todos los endpoints requieren autenticación con Bearer Token de OAuth 2.0 (App Only).

​

Agregar un webhook

POST /2/webhooks

Descripción:

Crea una configuración de webhook. Tu URL de callback https de acceso público debe incluirse en el cuerpo JSON.
Comencemos registrando una nueva URL de webhook para el contexto de la App indicada.

Autenticación:

OAuth2 App Only Bearer Token

• Bearer token <BEARER_TOKEN> p. ej., AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

Parámetros (cuerpo JSON):

{
    "url": "<tu URL de callback HTTPS accesible públicamente>"
}

• URL <URL> p. ej., https://yourdomain.com/webhooks/twitter/

Solicitud: Copia la siguiente solicitud de cURL en tu línea de comandos después de realizar los siguientes cambios:

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

Respuestas:

Correcto (200 OK)

Una respuesta satisfactoria indica que el webhook se creó y que la verificación CRC inicial se superó.

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

Error (400 Solicitud incorrecta)

Los errores devuelven un objeto de error estándar.

{
    "errors": [
      {
        "message": "<Motivo>: <Detalles>"
      }
    ],
    "title": "Solicitud no válida",
    "detail": "Uno o varios parámetros de su solicitud no eran válidos.",
    "type": "https://api.twitter.com/2/problems/invalid-request"
}

Las causas comunes de error incluyen:

Motivo	Descripción
CrcValidationFailed	La URL de callback no respondió correctamente a la verificación CRC (p. ej., se agotó el tiempo de espera, respuesta incorrecta).
UrlValidationFailed	La URL de callback proporcionada no cumple los requisitos (p. ej., no es https, formato no válido).
DuplicateUrlFailed	Tu aplicación ya tiene registrado un webhook para la URL de callback proporcionada.
WebhookLimitExceeded	Tu aplicación alcanzó el número máximo de configuraciones de webhook permitidas.

​

Visualización de un webhook

GET /2/webhooks

Descripción: Recupera todas las configuraciones de webhooks asociadas a tu App (cuenta de desarrollador).

Autenticación:

Token Bearer de OAuth2 (solo App)

• Token Bearer <BEARER_TOKEN> p. ej., AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

• URL <URL> p. ej., https://yourdomain.com/webhooks/twitter/

Solicitud: Ejecuta el siguiente comando para recuperar todas las URL de webhooks registradas y sus estados para la App indicada.

Copia la siguiente solicitud cURL en tu línea de comandos después de realizar los siguientes cambios:

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

Correcto (200 OK)

Devuelve una lista de configuraciones de webhooks. La lista estará vacía si no hay ningún webhook configurado.

Ejemplo (con un webhook configurado):

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

Ejemplo (sin webhooks configurados):

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

​

Eliminar un webhook

DELETE /2/webhooks/:webhook_id

Descripción: Elimina una configuración de webhook usando su webhook_id específico. El id puede obtenerse de la respuesta de creación POST /2/webhooks o de la respuesta de listado GET /2/webhooks.

Autenticación:

OAuth2 App Only Bearer Token

• Bearer token <BEARER_TOKEN> p. ej. AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

Parámetros de ruta:

Parámetro	Descripción
webhook_id	El id del webhook que se va a eliminar.

Solicitud: Ejecuta el siguiente comando para eliminar el webhook de la configuración de la App indicada.

Copia la siguiente solicitud cURL en tu línea de comandos después de realizar los siguientes cambios:

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

  **Respuestas:**

Éxito (200 OK)

Devuelve una respuesta JSON con el estado “deleted” en true si se elimina correctamente.

Ejemplo (con la eliminación correcta del webhook):

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

Error (400 Bad Request)

Motivo	Descripción
WebhookIdInvalid	El webhook_id proporcionado no se encontró o no está asociado con tu App.

​

Validar y reactivar el webhook

PUT /2/webhooks/:webhook_id

Descripción: Inicia la comprobación de respuesta al desafío (CRC) para la URL del webhook indicado. Si la comprobación es exitosa, devuelve 200 y reactiva el webhook estableciendo su estado en valid.

Autenticación:

OAuth2 App Only Bearer Token

• Token de portador (Bearer token) <BEARER_TOKEN> p. ej. AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

Parámetros de ruta:

Parámetro	Descripción
webhook_id	El id del webhook que se va a validar.

Solicitud: Ejecute el siguiente comando para validar el webhook desde la configuración de la App proporcionada.

Copie la siguiente solicitud cURL en su línea de comandos después de realizar los siguientes cambios:

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

  **Respuestas:**

Éxito (200 OK)

Una respuesta 200 OK indica que se inició la solicitud de verificación CRC. No garantiza que la verificación CRC haya sido satisfactoria. El campo valid en la respuesta refleja el estado después del intento de verificación. Si la verificación CRC se realiza correctamente, el estado del webhook se actualizará a válido. Puedes verificar el estado actual con GET /2/webhooks.

{
  "data": {
    "valid": true // Indica el estado tras completarse el intento de verificación de CRC
  }
}

Error (400 Solicitud incorrecta)

Motivo	Descripción
WebhookIdInvalid	No se encontró el webhook_id proporcionado o no está asociado con tu App.
CrcValidationFailed	La URL de callback no respondió correctamente a la solicitud de comprobación de CRC.

​

4. La comprobación CRC

La comprobación de respuesta al desafío (CRC, por sus siglas en inglés) es el mecanismo que usa X para verificar que la URL de callback que proporcionaste es válida y que está bajo tu control.

Cuándo se activa el CRC:

• En el registro inicial del webhook (POST /2/webhooks)
• Cada hora, por X, para validación
• Manualmente mediante PUT /2/webhooks/:id

Ejemplo:

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

Ejemplo de cuerpo de respuesta en JSON:

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

Cómo generar la respuesta:

• Usa crc_token como mensaje
• Usa el consumer secret de la App como clave
• Crea un hash HMAC SHA-256
• Codifica el resultado en Base64

​

Apps de ejemplo

• Servidor de webhook simple
  • Un script de Python único que muestra cómo responder a la verificación CRC y aceptar eventos POST.
• Panel de muestra de Account Activity API
  • Una app web creada con bun.sh que permite gestionar webhooks, suscripciones y recibir eventos en tiempo real directamente en la App.