Connect applications and automate work

Usable offers several integration mechanisms. Choose the smallest one that matches who decides the action, how quickly a result is needed, and who owns failures.

Choose the mechanism

Do not add a webhook when a direct request is sufficient, and do not give an AI agent write permissions for a deterministic batch job.

Define the integration contract

Before connecting anything, document:

• purpose and owner;
• exact workspace(s);
• data read or transmitted;
• required permissions;
• authentication method;
• trigger and expected result;
• duplicate and retry behavior;
• monitoring and removal procedure.

Treat the receiver, app, queue, logs, and backups as part of the workspace's data boundary.

Connect a marketplace app

1. Open Marketplace.
2. Review the app details and publisher.
3. Inspect requested permissions and callback/device flow.
4. Connect only to intended workspaces.
5. Complete consent.
6. Verify the app under installed applications.
7. Test a low-risk operation.

Disconnect applications that no longer have an owner or purpose.

Build with REST or MCP

Use the deployed OpenAPI document at https://usable.dev/api/docs for REST request schemas and route authentication.

For MCP, inspect tools/list from the target endpoint. The visible tool set and effective permissions can differ by client, token, workspace, and Hosted Zone routing.

Use dedicated credentials per integration. Store secrets outside Usable fragments, source control, logs, and public support messages.

Configure the first webhook

1. Build a public HTTPS receiver.
2. Authenticate incoming requests using the strongest released option.
3. Configure a webhook for one workspace.
4. Select only required events.
5. Trigger a manual test.
6. Confirm the test indicator, payload validation, and fast acknowledgment.
7. Prevent test events from causing production side effects.
8. Enable production processing only after review.

The released public fragment event workflow covers fragment.created, fragment.updated, and fragment.deleted.

Design for retries and duplicates

External automation should be idempotent:

• upsert by stable resource identity;
• deduplicate notifications and side effects;
• compare current state before applying older updates;
• tombstone deletions where history matters;
• retry transient failures with bounds and jitter;
• quarantine malformed or permanent failures;
• acknowledge webhooks quickly and process asynchronously.

Do not assume event order or exactly-once delivery.

Respect Hosted Zone boundaries

For Leaf-backed workspaces, private fragment/search/collection/symlink data operations belong on Leaf. Cloud must not silently handle private data-plane requests. Hosted Zone V1 does not support file upload/search/attach workflows; use a Cloud workspace when file payloads are required.

Verify the integration

Test:

• correct workspace and lowest role/token scope;
• successful and denied requests;
• malformed input;
• duplicate and out-of-order events;
• secret rotation;
• disable/disconnect behavior;
• logs without sensitive payloads;
• recovery after temporary downtime.

A successful webhook response proves acknowledgment, not downstream completion.

Operational checklist

Keep a non-sensitive record of integration owner, application/webhook ID, purpose, workspace, selected events or permissions, credential rotation date, monitoring location, and retirement procedure.

Review integrations when a maintainer leaves, a workspace changes visibility, a credential is exposed, permissions expand, or the downstream service changes ownership.

Troubleshooting

Connection or consent fails

Confirm the app is available to the account, redirects or Device Code instructions match the registered application, and the signed-in user can grant the requested access.

REST returns 401 or 403

Check authentication method, token expiry, workspace scope, and required permission. Some dashboard/billing routes are session-oriented and should not be assumed to accept PATs.

Webhook test succeeds but nothing happens

The receiver may acknowledge before asynchronous processing. Inspect queue and processing metrics using redacted identifiers.

Duplicate actions occur

Add a durable idempotency record and make state transitions repeatable.

Related pages

• Applications and integrations in Usable
• REST API overview
• Webhooks and automation in Usable
• Build a secure and reliable webhook receiver
• Configure permissions, access, and token security