Webhooks

Webhooks let your systems react to diagram changes in real time. Subscribe to lifecycle events and EntityFlow will POST a signed payload to your endpoint whenever they fire.

Events

Event	Fired when
diagram.created	A diagram is created.
diagram.updated	A diagram is saved/updated.
diagram.deleted	A diagram is deleted.

Creating a subscription

POST /api/v1/webhooks with a target url and the list of 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"]
      }'

The response includes a signing secret — shown once. Store it securely; you need it to verify deliveries.

Verifying deliveries

Every delivery carries Standard-Webhooks headers:

Header	Purpose
webhook-id	Unique delivery ID (use for idempotency).
webhook-timestamp	Send time (reject stale deliveries).
webhook-signature	v1,<HMAC-SHA256 of the payload using your secret>.

Always verify the signature before trusting a delivery. Recompute the HMAC-SHA256 of the raw request body using your signing secret and compare it (in constant time) against the v1,... value in webhook-signature.

tip

Use the Standard Webhooks libraries to verify signatures correctly across languages, rather than rolling your own.

HTTP targets

https targets are always allowed. Plaintext http targets are blocked by default as an SSRF guard. Self-hosters can permit them with:

export EF_WEBHOOK_ALLOW_HTTP=true

See the Configuration reference for related importer and network settings.