Webhooks del honeypot: envía las detecciones de ataques a cualquier API
La versión 1.3.0 del ReportedIP Honeypot Server, publicada el 12 de junio de 2026, convierte sus webhooks en un router configurable que envía cada detección de ataque a cualquier API HTTP. Cada endpoint define su propio método, sus cabeceras y su cuerpo, así que las detecciones llegan a un SIEM, a Slack, a Discord o a AbuseIPDB sin código de adaptación.
La versión actual es la 1.4.1 del 15 de septiembre de 2026, y todo lo que se describe aquí funciona igual en ella. La instalación y la lista completa de campos están en la documentación del Honeypot Server.
¿Qué hacen los webhooks del honeypot?
Un webhook es un endpoint HTTP o HTTPS que recibe una petición cada vez que el honeypot detecta un ataque que coincide con sus filtros. La función llegó con la versión 1.2.0 y un formato JSON fijo para sistemas de registro y SIEM. La versión 1.3.0 la abrió a cualquier API: Splunk, Elastic, un canal de Slack o Discord, o una segunda base de datos de abuso.
El honeypot envía los webhooks cuando la respuesta de la trampa ya ha llegado al atacante. Un endpoint lento o caído nunca retrasa lo que ve el atacante. Cuando salió la 1.3.0, la cadena de detección ejecutaba 36 analizadores, desde inyección SQL y cross-site scripting hasta path traversal y fuerza bruta. Desde la versión 1.3.10 ejecuta 40, y cualquiera de ellos puede disparar un webhook.
¿Cómo envías las detecciones del honeypot a cualquier API?
Hasta la versión 1.2.1, cada envío era un POST en JSON. Desde la 1.3.0, cada webhook define su propia petición:
- Método HTTP:
POST,PUT,PATCHoGET. Una petición GET no lleva cuerpo, los datos van entonces en la URL. - Cabeceras propias: una por línea, para claves de API y autenticación. Sustituyen a las cabeceras predeterminadas.
- Formato del cuerpo:
jsonestructurado,formcodificado para URL o una plantilla librecustom. - Marcadores: 13 campos como
{{ip}},{{categories}},{{severity}}y{{timestamp}}, utilizables en el cuerpo y en la URL. Cada campo existe además como{{..._url}}(codificado para URL) y{{..._json}}(escapado para JSON).
Cuando una petición activa varios analizadores, cada webhook recibe igualmente un solo envío. Los marcadores combinan las categorías, conservan la gravedad más alta y unen los comentarios. El formato JSON enumera cada detección por separado.
La correspondencia con AbuseIPDB viene integrada
Cada base de amenazas numera sus categorías a su manera, así que reportar a una segunda base exigía hasta ahora código de conversión propio. El marcador {{abuseipdb_categories}} se encarga de esa correspondencia: los ID 1 a 23 son idénticos en ambas plataformas, y las categorías de ReportedIP desde la 24 se traducen a su equivalente más cercano en AbuseIPDB. En la 1.3.0 la correspondencia cubría los ID 24 a 58. Desde la versión 1.3.7 cubre también las categorías de honeypot 59 a 63. Un reporte al endpoint de reportes de AbuseIPDB tiene este aspecto:
POST https://api.abuseipdb.com/api/v2/report
Key: <your-abuseipdb-api-key>
Accept: application/json
ip={{ip_url}}&categories={{abuseipdb_categories}}&comment={{comment_url}}Cuatro plantillas rellenan la petición
El formulario de webhooks ofrece cuatro plantillas rápidas (Quick Presets). Cada una rellena la URL, el método, las cabeceras y la plantilla del cuerpo. Después añades tu propia clave de API o la URL de tu webhook.
| Plantilla | Método | Formato del cuerpo |
|---|---|---|
| Generic JSON | POST | json |
| AbuseIPDB | POST | custom |
| Slack | POST | custom |
| Discord | POST | custom |
El botón de prueba envía una petición con la dirección de loopback 127.0.0.1. Las bases de abuso rechazan esa dirección, así que probar un webhook de AbuseIPDB nunca genera un reporte contra un host real.
¿Cómo configuras un webhook?
Los webhooks se gestionan en el panel de administración del honeypot, en Webhooks. La actualización a la 1.3.0 amplía por sí sola los ajustes de webhook guardados, no hace falta ninguna migración manual. Tres ajustes deciden qué recibe un endpoint:
- Filtro de categorías: ID de la lista de categorías de amenazas que usa todo ReportedIP.
- Filtro de analizadores: nombres de motores de detección, por ejemplo
SqlInjection. - Secret: opcional. Añade una firma HMAC-SHA256 a cada petición.
Con los dos filtros vacíos se envía cada detección. Con los dos definidos, una detección que coincida con cualquiera de ellos dispara el webhook. El panel muestra para cada endpoint el último estado, su hora y el número de fallos consecutivos, y un envío correcto pone ese número a cero. La referencia de webhooks describe cada campo.
¿Cómo es el payload JSON predeterminado?
Con el formato json, cada petición lleva Content-Type: application/json, una cabecera X-ReportedIP-Event con el valor detection o test y, si hay un secret definido, una cabecera X-ReportedIP-Signature. El cuerpo agrupa el honeypot, la petición y una o varias detecciones:
{
"event": "detection",
"generated_at": "2026-06-12T14:00:00+00:00",
"honeypot": {
"name": "reportedip-honeypot-server",
"version": "1.3.0",
"host": "your-honeypot.example.com",
"profile": "wordpress"
},
"request": {
"ip": "203.0.113.50",
"method": "POST",
"uri": "/wp-login.php",
"user_agent": "sqlmap/1.7"
},
"detections": [
{
"analyzer": "SqlInjection",
"categories": [16, 45],
"category_names": ["SQL Injection", "WP Database Injection"],
"comment": "SQL injection attempt detected: ...",
"severity": 85
}
]
}Comprueba la firma en el lado receptor
La firma es un HMAC-SHA256 sobre el cuerpo bruto de la petición con tu secret como clave (RFC 2104) y llega como sha256=<hex>. Calcula el mismo valor en tu lado y compara ambos en tiempo constante:
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$valid = hash_equals($expected, $_SERVER['HTTP_X_REPORTEDIP_SIGNATURE'] ?? '');Calcula el hash sobre los bytes brutos antes de cualquier parsing JSON. Un cuerpo analizado y vuelto a codificar puede cambiar en espacios u orden de claves, y la firma deja de coincidir. GitHub firma sus webhooks con el mismo formato sha256=, así que el código receptor que ya tengas solo necesita otro nombre de cabecera.
¿Por qué enviar las detecciones del honeypot a un SIEM?
Un honeypot solo es útil si alguien ve lo que captura. Sin webhooks, sus detecciones quedaban en un panel de administración aparte, lejos de todas las demás señales de seguridad. Con webhooks llegan junto a los registros del firewall, del WAF y de las aplicaciones como campos estructurados que puedes correlacionar, usar para alertas o pasar a una lista de bloqueo. La misma detección puede ir a la vez a ReportedIP y a AbuseIPDB.
Los webhooks también encajan en flotas de servidores. Si gestionas varios servidores, como en la guía sobre cómo proteger un clúster de servidores, un solo honeypot puede alimentar un colector central que consulta el resto del clúster.
¿Qué cambió entre las versiones 1.2.0 y 1.3.0?
Las versiones 1.2.0, 1.2.1 y 1.3.0 salieron todas el 12 de junio de 2026. La 1.2.0 introdujo los webhooks y corrigió tres problemas: faltaban los rangos IPv6 de Cloudflare en la detección de la IP del cliente, el analizador de cabeceras tomaba direcciones IPv6 legítimas por loopback, y los reportes que la API había rechazado de forma definitiva bloqueaban la cola de reportes.
La 1.2.1 fue un hotfix para un error HTTP 500 en la página Webhooks justo después de actualizar, causado por un autoloader desactualizado. La 1.3.0 convirtió el envío en el router descrito arriba, añadió la correspondencia con AbuseIPDB y las plantillas, combinó varias detecciones por petición y llevó la batería de pruebas a 363 tests.
Desde entonces, la 1.3.1 corrigió el mismo día el texto de ayuda y las plantillas de la página Webhooks, la 1.3.3 añadió las categorías de honeypot 59 a 63, y la 1.3.7 alineó la correspondencia con AbuseIPDB con los nombres de categoría corregidos. Si todavía usas una versión anterior, actualiza directamente a la 1.4.1.
Preguntas frecuentes sobre los webhooks del honeypot
¿Puede el honeypot reportar a AbuseIPDB?
El honeypot reporta a AbuseIPDB mediante su plantilla integrada. La plantilla fija el endpoint de reportes, una plantilla de cuerpo propia y el marcador {{abuseipdb_categories}}, que traduce las categorías de ReportedIP a ID de AbuseIPDB. Pon tu propia clave de API de AbuseIPDB en la cabecera Key, envía una prueba y cada detección que coincida irá a las dos bases.
¿Hacen los webhooks más lento el honeypot?
El envío nunca retrasa la respuesta que ve el atacante, porque el honeypot manda los webhooks solo después de que haya salido la respuesta de la trampa. Por eso un endpoint lento no puede delatar la trampa por los tiempos de respuesta. Un envío fallido solo aumenta el contador de fallos del panel, y la detección y los reportes a ReportedIP siguen funcionando igual.
¿Cómo sé que un payload viene de mi honeypot?
Un secret en el webhook demuestra de dónde viene una petición. Con un secret definido, cada petición lleva una cabecera X-ReportedIP-Signature con un HMAC-SHA256 del cuerpo bruto. Tu receptor calcula el mismo valor con el mismo secret y compara ambos en tiempo constante. Descarta cualquier petición cuya firma no coincida.
Consigue el Honeypot Server
El código del Honeypot Server se puede consultar libremente (source-available) bajo la Business Source License 1.1 y pasará a Apache 2.0 el 1 de marzo de 2030. Puedes usarlo en producción para tu propia infraestructura, pero no ofrecerlo a terceros como servicio alojado. Necesita PHP 8.2 con SQLite y cURL, sin paquetes externos.
- Documentación del Honeypot Server: instalación, configuración y referencia de webhooks.
- Productos de ReportedIP: el plugin Hive, la API, el feed de la blacklist y las herramientas gratuitas, entre ellas el honeypot.
- Blacklist comunitaria: convierte a los atacantes reportados en una lista de bloqueo para tu firewall.