Skip to main content
Esta guía te acompaña en la configuración de una app consumidora de webhook, la implementación del Challenge-Response Check (CRC), la seguridad de los eventos entrantes y el registro de tu webhook con X.

1. Desarrolla una app consumidora de webhook

Para registrar un webhook con tu X app, debes desarrollar, desplegar y hospedar una web app que reciba eventos de webhook de X y responda a solicitudes de seguridad CRC.

Requisitos de URL

Crea una web app con una URL HTTPS accesible públicamente que actuará como el endpoint del webhook para recibir eventos:
  • El path del URI depende de ti. Todos estos ejemplos son válidos:
    • https://mydomain.com/service/listen
    • https://mydomain.com/webhook/twitter
  • La URL no puede incluir una especificación de puerto (por ejemplo, https://mydomain.com:5000/webhook no funcionará)

Lo que tu app debe manejar

Tu endpoint de webhook debe manejar dos tipos de solicitudes HTTP:

2. La verificación CRC

El Challenge-Response Check (CRC) es la forma en que X valida que la URL de callback que proporcionaste es válida y que tú la controlas. Tu web app debe responder correctamente a las solicitudes CRC para registrar y mantener tu webhook.

Cuándo se dispara CRC

Si tu webhook falla una verificación CRC, se marcará como invalid y dejará de recibir eventos hasta que la vuelva a pasar.

Cómo funciona el CRC

Cuando X envía un CRC, hace una solicitud GET a la URL de tu webhook con un parámetro de consulta crc_token:
Tu aplicación debe responder con un cuerpo JSON que contenga un response_token:

Cómo construir la respuesta CRC

  1. Usa el valor de crc_token del parámetro de consulta como el mensaje
  2. Usa el consumer secret de tu app (API secret key) como la clave
  3. Crea un hash HMAC SHA-256
  4. Codifica el resultado en Base64
  5. Antepone sha256= a la cadena codificada
Importante: Tu web app debe usar el consumer secret de tu app (API secret key) para el cifrado CRC — no tu bearer token ni access token.

Ejemplo: Python

Ejemplo

Ejemplo: Node.js

Ejemplo

Ejemplo: Flask (endpoint completo)

Este ejemplo muestra un endpoint de webhook completo que maneja tanto la validación CRC (GET) como la entrega de eventos (POST):
Ejemplo

3. Asegurar webhooks

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

Challenge-Response Check (CRC)

El CRC permite a X confirmar la propiedad de la web app que recibe los eventos de webhook. Consulta el Paso 2 más arriba para los detalles completos de implementación.

Verificación de firma

Cada solicitud POST de X incluye una cabecera x-twitter-webhooks-signature que te permite confirmar que X es la fuente del webhook entrante. Para verificar la firma:
  1. Obtén el valor de la cabecera x-twitter-webhooks-signature de la solicitud entrante
  2. Crea un hash HMAC SHA-256 usando tu consumer secret como clave y el cuerpo crudo de la solicitud como mensaje
  3. Codifica el hash en Base64 y antepone sha256=
  4. Compara el valor calculado con el valor de la cabecera — deben coincidir
Ejemplo

4. Registra tu webhook

Una vez que tu app pueda manejar las verificaciones CRC, registra la URL de tu webhook haciendo una solicitud POST /2/webhooks. Cuando hagas esta solicitud, X enviará inmediatamente una solicitud CRC a tu web app para verificar la propiedad. Todos los endpoints de gestión de webhook requieren autenticación con OAuth2 App Only Bearer Token.

Crear un webhook

POST /2/webhooksReferencia de la API
Respuesta exitosa (200 OK): Una respuesta exitosa indica que el webhook fue creado y la verificación CRC inicial pasó.
Cuando un webhook se registra con éxito, la respuesta incluye un webhook ID. Este ID se necesita al hacer solicitudes a productos que soportan webhooks (por ejemplo, enlazar con Filtered Stream o crear suscripciones para Account Activity). Razones comunes de fallo:

Ver webhooks

GET /2/webhooksReferencia de la API Recupera todas las configuraciones de webhook asociadas con tu aplicación.
Respuesta (con un webhook):
Respuesta de ejemplo
Respuesta (sin webhooks):

Eliminar un webhook

DELETE /2/webhooks/:webhook_idReferencia de la API Elimina un webhook usando su webhook_id (obtenido de la respuesta de creación o listado).
Respuesta:

Validar y volver a habilitar un webhook

PUT /2/webhooks/:webhook_idReferencia de la API Dispara una verificación CRC para el webhook dado. Si la verificación tiene éxito, el webhook se vuelve a habilitar con valid: true.
Respuesta: Una respuesta 200 OK indica que la verificación CRC se inició. El campo valid refleja el estado después del intento de verificación. Puedes verificar el estado actual usando GET /2/webhooks.

Pruebas con xurl

Para propósitos de prueba, la herramienta xurl admite webhooks temporales. Instala la última versión del proyecto xurl desde GitHub, configura tu autorización y luego ejecuta:
Esto generará una URL de webhook pública temporal, manejará automáticamente todas las verificaciones CRC y registrará los eventos de suscripción entrantes. Es una excelente manera de verificar tu configuración antes del despliegue. Ejemplo de salida:

Notas importantes

  • Todos los Direct Messages entrantes se entregarán vía webhooks. Los DMs enviados vía POST /2/dm_conversations/with/:participant_id/messages también se entregarán, para que tu app pueda rastrear DMs enviados desde otros clientes.
  • Si tienes más de una web app que comparte la misma URL de webhook y el mismo usuario mapeado a cada app, el mismo evento se enviará a tu webhook varias veces (una por web app).
  • En algunos casos, tu webhook puede recibir eventos duplicados. Tu app de webhook debe tolerar esto y deduplicar por ID de evento.
  • X envía los eventos como solicitudes POST con payloads JSON. Consulta la estructura del objeto de datos de Account Activity para ver payloads de ejemplo.

Apps de ejemplo


Próximos pasos

Filtered Stream Webhooks

Recibe Posts filtrados vía webhook

Account Activity API

Recibe eventos de cuenta vía webhook