Webhooks

I webhook consentono ai tuoi sistemi di reagire in tempo reale alle modifiche dei diagrammi. Iscriviti agli eventi del ciclo di vita ed EntityFlow invierà una richiesta POST con un payload firmato al tuo endpoint ogni volta che si attivano.

Eventi

Evento	Attivato quando
diagram.created	Viene creato un diagramma.
diagram.updated	Un diagramma viene salvato/aggiornato.
diagram.deleted	Un diagramma viene eliminato.

Creare una sottoscrizione

POST /api/v1/webhooks con una url di destinazione e l'elenco degli 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 risposta include un segreto di firma — mostrato una sola volta. Conservalo in modo sicuro; ti serve per verificare le consegne.

Verificare le consegne

Ogni consegna include intestazioni Standard-Webhooks:

Intestazione	Scopo
webhook-id	Identificatore univoco della consegna (usalo per l'idempotenza).
webhook-timestamp	Ora di invio (rifiuta le consegne obsolete).
webhook-signature	v1,<HMAC-SHA256 of the payload using your secret>.

Verifica sempre la firma prima di considerare attendibile una consegna. Ricalcola l'HMAC-SHA256 del corpo grezzo della richiesta utilizzando il tuo segreto di firma e confrontalo (a tempo costante) con il valore v1,... presente in webhook-signature.

suggerimento

Usa le librerie Standard Webhooks per verificare correttamente le firme nei vari linguaggi, anziché realizzare una soluzione personalizzata.

Destinazioni HTTP

Le destinazioni https sono sempre consentite. Le destinazioni http in chiaro sono bloccate per impostazione predefinita come protezione contro l'SSRF. Chi effettua l'auto-hosting può consentirle con:

export EF_WEBHOOK_ALLOW_HTTP=true

Consulta la documentazione di configurazione per le relative impostazioni dell'importatore e di rete.