¿Qué es un webhook?
ChainPatrol usa Webhooks (notificaciones automáticas que la plataforma envía a otro sistema) para avisarte sobre los cambios en nuestra Blocklist (lista de bloqueo) global. Esto te permite actualizar tu Blocklist en tiempo real, sin tener que esperar a que se ejecute un cron job programado. Es especialmente útil si optas por usar nuestro endpoint Listar assets para sincronizar nuestros datos, ya que puedes actualizar tu Blocklist apenas actualicemos la nuestra.Administrar Webhooks
Puedes administrar tus webhooks desde el Dashboard (panel principal) de ChainPatrol, en Developer › Webhooks en la barra lateral. Desde ahí puedes:- Crear nuevos webhooks
- Ver y monitorear las entregas de los webhooks
- Probar los webhooks con eventos de ejemplo
- Habilitar/deshabilitar webhooks
- Actualizar la configuración de los webhooks
- Eliminar webhooks
Tipos de eventos
debug.test
Este evento se usa para probar el endpoint de tu webhook. Se envía cuando haces clic en el botón “Test” de un webhook en el dashboard.
asset.status-updated
Este evento se envía cuando cambia el estado de un Asset (activo digital: URL, dirección, perfil, app, etc.). El campo status puede ser BLOCKED, ALLOWED o UNKNOWN.
asset.status-escalated
Este evento se envía cuando ChainPatrol escala una amenaza a tu organización para que la revise. Suscríbete a él para saber cuándo algo necesita una decisión de tu equipo, por ejemplo, para abrir un ticket o avisar a un canal de guardia.
Se dispara cuando:
- Un analista de ChainPatrol pasa una Proposal (propuesta para bloquear o permitir un asset) a tu organización para su revisión.
- Tu organización tiene habilitada la opción Obligatory Admin Approval (aprobación obligatoria de un administrador) y un analista aprueba una Proposal. Luego, la Proposal queda a la espera de la aprobación final de tu organización.
Si una Proposal se escala a tu organización más de una vez, recibes un evento cada vez. Usa
proposal_id para eliminar duplicados.asset.escalation-resolved
Este evento es la contraparte de asset.status-escalated. Se envía una sola vez cuando una amenaza que se había escalado a tu organización ya no necesita tu revisión, para que puedas cerrar lo que hayas abierto cuando llegó el escalamiento.
Se dispara cuando:
- Alguien de tu organización aprueba o rechaza la Proposal, la agrega a la Watchlist (lista de seguimiento de assets sospechosos que se siguen monitoreando) o la devuelve al equipo de ChainPatrol.
- ChainPatrol resuelve el escalamiento en tu nombre, por ejemplo, cuando un analista da curso a la Proposal mientras todavía está esperando tu respuesta.
El payload no incluye el estado del asset. Aprobar una Proposal bloquea el asset poco después, no de inmediato, así que suscríbete a
asset.status-updated si necesitas el estado final.organization.threat-detection-added
Este evento se envía cuando se agrega una nueva amenaza sospechosa a la página Suspected Threats (amenazas sospechosas detectadas automáticamente, todavía sin confirmar) de tu organización. Una amenaza sospechosa no está confirmada hasta que se revisa. El nombre del evento y la clave threat_detection_result_id conservan la nomenclatura de detección de la API.
audit-log.created
Este evento se envía cuando se registra una acción en el Audit Log (registro de auditoría) de tu organización, por ejemplo, cuando se edita una marca, se agrega o se elimina un miembro, o se crea una clave de API. Contiene lo mismo que ven tus administradores en la página Audit Log. Úsalo para transmitir esos cambios a un SIEM.
Configuración del webhook
Al crear un webhook, tendrás que proporcionar:- Una URL de endpoint HTTPS que recibirá los eventos del webhook
- Una descripción opcional que ayude a identificar el propósito del webhook
- Los eventos que quieres recibir (los eventos disponibles incluyen
asset.status-updated,asset.status-escalated,asset.escalation-resolved,organization.threat-detection-addedyaudit-log.created) - Encabezados HTTP opcionales para las integraciones compatibles (actualmente están disponibles los encabezados de Google SecOps)
Encabezados HTTP personalizados
ChainPatrol admite encabezados HTTP específicos y predefinidos (hardcoded) que se pueden configurar para las solicitudes de webhook. Actualmente, los siguientes encabezados están disponibles para la integración con Google SecOps:X-goog-api-key: Tu clave de API de GoogleX-Webhook-Access-Key: Tu clave de acceso del webhook
Verificación de la firma
ChainPatrol firma cada solicitud de webhook para que puedas verificar que la solicitud provino de ChainPatrol. La firma se incluye en el encabezadoX-ChainPatrol-Signature de cada solicitud. La firma se calcula tomando el HMAC SHA256 del cuerpo de la solicitud, usando el secreto de tu webhook como clave. La firma se codifica como una cadena hexadecimal.
Estado de entrega y reintentos
Cada intento de entrega de un webhook se registra con uno de los siguientes estados:PENDING: La entrega está en colaIN_PROGRESS: Se está intentando la entregaSUCCESS: La entrega fue exitosa (se recibió una respuesta 2xx)FAILURE: La entrega falló
- Un código de estado
2xxse registra comoSUCCESS. - Cualquier otro código de estado se registra como
FAILURE. Las redirecciones (3xx) no se siguen, así que configura la URL del webhook con la dirección final. - Si tu endpoint no responde en 30 segundos, la entrega se registra como
FAILUREy no se reintenta, porque es posible que tu endpoint ya la haya procesado.
Seguridad
Los webhooks se envían por HTTPS y se firman con un secreto que es único para tu cuenta. Debes:- Usar solo endpoints HTTPS
- Mantener seguro el secreto de tu webhook y nunca subirlo a un sistema de control de versiones
- Verificar siempre la firma de los webhooks entrantes
- Contactarnos de inmediato si sospechas que el secreto de tu webhook se vio comprometido