Consola > Webhooks para crear, probar, activar, desactivar, editar y dar seguimiento a las entregas.
Cuándo usar
Usa webhooks cuando:- un sistema externo necesita reaccionar a eventos de Acrity;
- una automatización interna debe recibir notificaciones;
- necesitas alimentar observabilidad, auditoría o dashboards;
- las integraciones mediante API polling no son deseables.
Consola > API Keys cuando el sistema externo necesite consultar datos activamente.
Quién puede acceder
Gestionar webhooks requiere un administrador de workspace (los administradores de plataforma también tienen acceso). Los roles son conjuntos de capacidades fijas definidos por Acrity, no configurables por workspace.Campos principales
| Campo | Para qué sirve |
|---|---|
| Nombre | Identifica el webhook en la Consola. |
| URL | Endpoint externo que recibirá el evento. |
| Método | Método HTTP usado en la entrega. |
| Content type | Formato del cuerpo enviado. |
| Eventos | Tipos de evento que disparan el webhook. |
| Headers | Encabezados adicionales enviados en la solicitud. |
| Headers secretos | Encabezados cuyo valor debe protegerse y no volver a mostrarse. |
| HMAC | Firma que permite al destinatario verificar el origen. |
| Body template | Plantilla opcional para personalizar el payload enviado. |
| Ignorar verificación SSL | Omite la validación del certificado TLS del destino. Opción excepcional para entornos controlados. Evítala en producción. |
Crear un webhook
Configurar seguridad
Agrega los headers necesarios y habilita HMAC cuando el destinatario pueda validar firmas.
Probar
Usa la acción Probar evento para enviar una entrega de muestra y previsualizar la solicitud antes de habilitar en producción.
Headers y secretos
Usa headers para enviar tokens, identificadores o información requerida por el destino. Buenas prácticas:- marca como secreto cualquier header que contenga un token o secreto;
- no pongas secretos en el nombre del webhook;
- prefiere la rotación de tokens en el sistema destinatario;
- elimina los headers que no se usan;
- documenta internamente al responsable del endpoint.
HMAC
HMAC permite que el sistema destinatario valide que el payload vino de Acrity y no fue alterado en tránsito. Usa HMAC siempre que el destino soporte la verificación de firma. Al habilitar:- Genera o introduce un secreto fuerte.
- Configura el mismo secreto en el sistema destinatario.
- Prueba una entrega.
- Rechaza en el destino los payloads sin una firma válida.
Body template
El body template personaliza el cuerpo enviado. Úsalo cuando el destino espera un formato específico. Recomendaciones:- empieza con un payload simple;
- valida con la previsualización antes de guardar;
- evita incluir datos sensibles innecesarios;
- mantén la compatibilidad con el sistema destinatario;
- versiona los cambios importantes del lado del receptor.
Probar entrega
Antes de activar un webhook crítico:- usa la acción Probar evento;
- confirma el estado de respuesta del destino;
- verifica los logs del sistema receptor;
- valida la firma HMAC cuando esté habilitada;
- revisa los headers y el content type;
- confirma que llegó el payload esperado.
Historial de entregas
La página de detalle del webhook puede mostrar el historial de entregas. Usa este historial para investigar:- envíos exitosos o fallidos;
- el estado devuelto por el destino;
- el tiempo de respuesta;
- el payload de prueba o de entrega cuando la pantalla lo muestre;
- errores de conexión, TLS o validación.
Activar y desactivar
Desactiva un webhook cuando:- el destino está en mantenimiento;
- el endpoint fue reemplazado;
- hay sospecha de un secreto expuesto;
- la integración está generando ruido;
- necesitas pausar las entregas temporalmente.
Problemas comunes
| Síntoma | Qué verificar |
|---|---|
| El webhook no guarda | Revisa URL, método, content type, eventos y las validaciones de la pantalla. |
| La prueba devuelve un error | Verifica si el endpoint es accesible públicamente o a través de la red esperada. |
| El destino rechaza el payload | Revisa el content type, la plantilla y el schema esperado por el receptor. |
| Firma inválida | Verifica el secreto HMAC en ambos lados y si el receptor usa el payload en bruto correcto. |
| Error de TLS | Corrige el certificado del destino. Evita ignorar SSL en producción. |
Seguridad
Los webhooks pueden enviar datos operativos fuera de Acrity. Configura solo destinos de confianza y revisa periódicamente qué eventos están activos. Los detalles sobre el tratamiento de datos están enSeguridad > Tratamiento de datos.