Webhooks

Los webhooks permiten que tus sistemas reaccionen a los cambios en los diagramas en tiempo real. Suscríbete a los eventos del ciclo de vida y EntityFlow enviará una solicitud POST con una carga útil firmada a tu endpoint cada vez que se activen.

Eventos

Evento	Se activa cuando
diagram.created	Se crea un diagrama.
diagram.updated	Se guarda/actualiza un diagrama.
diagram.deleted	Se elimina un diagrama.

Crear una suscripción

POST /api/v1/webhooks con una url de destino y la lista de events:

curl -X POST https://<your-host>/api/v1/webhooks \
  -H "Authorization: Bearer ef_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://example.com/hooks/entityflow",
        "events": ["diagram.created", "diagram.updated", "diagram.deleted"]
      }'

La respuesta incluye un secreto de firma — que se muestra una sola vez. Guárdalo de forma segura; lo necesitas para verificar las entregas.

Verificar las entregas

Cada entrega incluye encabezados Standard-Webhooks:

Encabezado	Propósito
webhook-id	Identificador único de entrega (úsalo para la idempotencia).
webhook-timestamp	Hora de envío (rechaza las entregas obsoletas).
webhook-signature	v1,<HMAC-SHA256 of the payload using your secret>.

Verifica siempre la firma antes de confiar en una entrega. Vuelve a calcular el HMAC-SHA256 del cuerpo sin procesar de la solicitud usando tu secreto de firma y compáralo (en tiempo constante) con el valor v1,... del encabezado webhook-signature.

tip

Usa las bibliotecas de Standard Webhooks para verificar las firmas correctamente en todos los lenguajes, en lugar de crear tu propia solución.

Destinos HTTP

Los destinos https siempre están permitidos. Los destinos http en texto plano están bloqueados de forma predeterminada como protección contra SSRF. Quienes realizan el autoalojamiento pueden permitirlos con:

export EF_WEBHOOK_ALLOW_HTTP=true

Consulta la referencia de configuración para conocer los ajustes relacionados del importador y de la red.