Webhooks and automation in Usable
Bergur DavidsenUpdated 2026-07-14
Usable automation turns workspace changes into controlled actions. Released options include outbound workspace webhooks, email notification rules, and tag-driven fragment auto-link rules.
Choose the smallest mechanism that meets the need:
- use a webhook to notify an external HTTPS service;
- use an email notification rule to notify selected people;
- use an auto-link rule to create cross-workspace symlink relationships from tags;
- use REST or MCP for deterministic or agent-controlled actions that should not be event-driven.
Workspace webhooks
A webhook sends an HTTP request to a configured target when a selected workspace event occurs. Released public workflows cover fragment-created, fragment-updated, and fragment-deleted notifications, plus a manual test trigger using existing fragment data.
Webhooks are workspace-scoped. A webhook configured in one workspace does not subscribe to all workspaces the user can access.
Delivery is not authorization
A receiver URL and auth header authorize delivery to the receiver; they do not grant that receiver independent access to Usable. Payloads can contain workspace and fragment data, so the webhook itself crosses a data boundary.
Before enabling one, confirm:
- the destination is approved for the workspace's data;
- HTTPS and receiver authentication are configured;
- only required event types are selected;
- the receiver validates requests and payloads;
- retries and duplicate events are safe;
- an owner is responsible for monitoring and removal.
Other automation
Email notification rules
Where exposed in workspace settings, notification rules can send email for events such as fragment creation or updates. Keep recipients and event filters narrow. Email delivery history can be best-effort; verify mailbox delivery separately from audit records.
Auto-link rules
Auto-link rules match tags in a source workspace and create symlink children in a target workspace. Released controls include preview, create, enable/disable, update, delete, and reprocess.
Auto-linking changes knowledge organization, not an external HTTP integration. Preview every rule and verify both workspace boundaries.
Choose event-driven or direct calls
Use event-driven automation when a downstream service reacts to changes, delayed or duplicate processing is acceptable, and the receiver can acknowledge quickly and process asynchronously.
Use direct REST or MCP when a caller needs an immediate result, strict request/response control, or human/agent selection of the target.
Safe lifecycle
define purpose → choose events → build receiver → configure test target → trigger tests → verify security → enable production → monitor → rotate or disableDo not point an untested webhook at a destructive production workflow.
Permissions
Managing workspace webhooks is a workspace-management action and can require elevated workspace access. Manual testing also checks workspace and fragment access. Exact session or bearer-token support depends on the deployed route; inspect GET /api/docs and prefer the dashboard where the route is session-oriented.
Subscribers and read-only users should not expect to create or change automations.
Hosted Zones
Hosted Zone placement creates an explicit Cloud/Leaf boundary. Private Leaf workspace data must not silently fall back to Cloud. Use the released Hosted Zone endpoint and routing contract for private data-plane operations, and verify where webhook configuration and delivery are owned before enabling automation.