Saltar al contenido principal

¿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:
  1. Crear nuevos webhooks
  2. Ver y monitorear las entregas de los webhooks
  3. Probar los webhooks con eventos de ejemplo
  4. Habilitar/deshabilitar webhooks
  5. Actualizar la configuración de los webhooks
  6. Eliminar webhooks
Cada entrega de webhook queda registrada y se puede inspeccionar para depurar, incluidos los detalles completos de la solicitud y de la respuesta.

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.
No se envía cuando una Proposal se escala internamente dentro del equipo de ChainPatrol. Tampoco se envía para los elementos que se mueven en bloque a tu cola de revisión cuando se activa Obligatory Admin Approval por primera vez.
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.
No se envía para las revisiones que dejan la Proposal a la espera de tu organización.
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:
  1. Una URL de endpoint HTTPS que recibirá los eventos del webhook
  2. Una descripción opcional que ayude a identificar el propósito del webhook
  3. Los eventos que quieres recibir (los eventos disponibles incluyen asset.status-updated, asset.status-escalated, asset.escalation-resolved, organization.threat-detection-added y audit-log.created)
  4. Encabezados HTTP opcionales para las integraciones compatibles (actualmente están disponibles los encabezados de Google SecOps)
El secreto del webhook se genera automáticamente y se te muestra una sola vez al crear el webhook. Asegúrate de copiarlo, porque no se volverá a mostrar.

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 Google
  • X-Webhook-Access-Key: Tu clave de acceso del webhook
Al configurar un webhook para Google SecOps, puedes proporcionar valores para estos encabezados, y se incluirán automáticamente en todas las solicitudes de webhook enviadas a tu endpoint, lo que le permite a Google SecOps autenticar y procesar los eventos 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 encabezado X-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.
Puedes verificar la firma de una solicitud calculando la firma por tu cuenta y comparándola con la firma incluida en la solicitud. Si las dos firmas coinciden, puedes estar seguro de que la solicitud provino de ChainPatrol. Este es un ejemplo de cómo verificar la firma en Node.js:

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 cola
  • IN_PROGRESS: Se está intentando la entrega
  • SUCCESS: La entrega fue exitosa (se recibió una respuesta 2xx)
  • FAILURE: La entrega falló
Una entrega se reintenta solo cuando ChainPatrol no pudo llegar a tu endpoint en absoluto, por ejemplo, si la conexión fue rechazada. En ese caso se reintenta hasta 3 veces. Una vez que tu endpoint responde, la entrega no se reintenta, sea cual sea la respuesta:
  • Un código de estado 2xx se registra como SUCCESS.
  • 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 FAILURE y no se reintenta, porque es posible que tu endpoint ya la haya procesado.
Puedes ver el estado de entrega, el payload y los detalles de la solicitud y de la respuesta de cada intento de webhook en el dashboard.

Seguridad

Los webhooks se envían por HTTPS y se firman con un secreto que es único para tu cuenta. Debes:
  1. Usar solo endpoints HTTPS
  2. Mantener seguro el secreto de tu webhook y nunca subirlo a un sistema de control de versiones
  3. Verificar siempre la firma de los webhooks entrantes
  4. Contactarnos de inmediato si sospechas que el secreto de tu webhook se vio comprometido
Si necesitas rotar el secreto de tu webhook, puedes eliminar el webhook existente y crear uno nuevo con la misma configuración.