Webhooks
Los webhooks permiten que tus sistemas reaccionen a lo que ocurre en freedam en lugar de preguntar constantemente. Cuando un recurso termina de importarse, se crea un enlace para compartir o se completa un trabajo grande, freedam notifica a una dirección web que eliges en cuestión de segundos: así tu CMS puede recoger la nueva imagen principal, tu bot de Slack puede anunciar la carpeta de la campaña o tu flujo de trabajo puede iniciar el paso siguiente, sin que nadie actualice una página.
Qué hace
Registras una o varias direcciones y eliges de qué eventos debe enterarse cada una. Los eventos cubren los momentos principales de la biblioteca:
- Recursos: creado, actualizado, eliminado, restaurado
- Colecciones: creada, actualizada, eliminada
- Enlaces para compartir: creado, revocado
- Flujos: un lote de importación que termina o un trabajo en segundo plano que se completa
- Pruebas: un evento de práctica que puedes activar a demanda para comprobar tu configuración
Cada notificación incluye el tipo de evento, cuándo ocurrió y los detalles del recurso, la colección o el enlace para compartir implicado.
Cómo funciona
Configuras los endpoints en el área de administración, en API → Webhooks (o mediante la API). Cada endpoint recibe un secreto de firma, que se muestra una sola vez: tu sistema lo usa para confirmar que las notificaciones entrantes provienen realmente de tu instancia de freedam y no están falsificadas ni repetidas. Si usas el SDK de TypeScript, esa verificación es una sola llamada.
La entrega está pensada para ser fiable. Si tu sistema está caído un momento o tarda en responder, freedam reintenta la notificación varias veces durante las horas siguientes, espaciando los intentos. Si un endpoint sigue fallando, se desactiva automáticamente en lugar de insistir sin fin.
Y cuando algo sale mal, no tienes que rastrear registros del servidor. Cada endpoint conserva un historial de entregas, con cada intento reciente, su resultado, cuánto tardó y qué respondió tu servidor, visible en la interfaz de administración. También puedes enviar un evento de prueba en cualquier momento para comprobar una configuración nueva antes de que llegue tráfico real.
Conviene saber
- Los endpoints deben usar HTTPS y responder rápido: confirma primero y haz el trabajo pesado después.
- Los secretos se rotan sin problemas. Puedes emitir un nuevo secreto de firma en cualquier momento, y el anterior deja de funcionar de inmediato. Rótalo cuando un compañero se vaya o ante una sospecha de filtración.
- Puedes pausar sin eliminar: marca un endpoint como inactivo para silenciarlo conservando su configuración.
- Gestionar los webhooks mediante la API usa los mismos tokens y permisos que todo lo demás.
El contrato técnico completo (encabezados, formas de las cargas útiles y ejemplos de verificación) está en la documentación de la API. ¿Quieres ver cómo funciona de principio a fin? Prueba la demostración.