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/listenhttps://mydomain.com/webhook/twitter
- La URL no puede incluir una especificación de puerto (por ejemplo,
https://mydomain.com:5000/webhookno 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 consultacrc_token:
response_token:
Cómo construir la respuesta CRC
- Usa el valor de
crc_tokendel parámetro de consulta como el mensaje - Usa el consumer secret de tu app (API secret key) como la clave
- Crea un hash HMAC SHA-256
- Codifica el resultado en Base64
- Antepone
sha256=a la cadena codificada
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 cabecerax-twitter-webhooks-signature que te permite confirmar que X es la fuente del webhook entrante.
Para verificar la firma:
- Obtén el valor de la cabecera
x-twitter-webhooks-signaturede la solicitud entrante - Crea un hash HMAC SHA-256 usando tu consumer secret como clave y el cuerpo crudo de la solicitud como mensaje
- Codifica el hash en Base64 y antepone
sha256= - 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 solicitudPOST /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/webhooks — Referencia de la API
Ver webhooks
GET /2/webhooks — Referencia de la API
Recupera todas las configuraciones de webhook asociadas con tu aplicación.
Respuesta de ejemplo
Eliminar un webhook
DELETE /2/webhooks/:webhook_id — Referencia de la API
Elimina un webhook usando su webhook_id (obtenido de la respuesta de creación o listado).
Validar y volver a habilitar un webhook
PUT /2/webhooks/:webhook_id — Referencia 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.
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 herramientaxurl admite webhooks temporales. Instala la última versión del proyecto xurl desde GitHub, configura tu autorización y luego ejecuta:
Notas importantes
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