Configure a workspace webhook

A workspace webhook sends selected Usable events to an external HTTPS receiver. Configure it only after the receiver is ready to validate requests, acknowledge quickly, and handle duplicates safely.

Before configuring

Prepare the exact workspace, an approved public HTTPS receiver URL, required fragment events, receiver authentication, a test receiver, an owner, and a monitoring/removal plan.

Do not use localhost, private network destinations, insecure HTTP, credentials in query strings, or shared receiver URLs whose audience is unclear.

Configure from the dashboard

1. Open the target workspace.
2. Go to Settings → Webhooks.
3. Choose New webhook.
4. Enter a descriptive name.
5. Add the exact HTTPS target URL.
6. Select only required events.
7. Add supported authentication headers where exposed.
8. Save the webhook in the intended enabled state.
9. Trigger a test with a representative fragment.
10. Confirm the receiver and Usable delivery result.

Released public testing covers fragment.created, fragment.updated, and fragment.deleted. Do not assume additional event types are released because draft or internal contracts mention them.

REST management routes

The released public REST directory includes:

GET    /api/workspaces/{id}/webhooks
POST   /api/workspaces/{id}/webhooks
GET    /api/workspaces/{id}/webhooks/{webhookId}
PATCH  /api/workspaces/{id}/webhooks/{webhookId}
DELETE /api/workspaces/{id}/webhooks/{webhookId}
POST   /api/workspaces/{id}/webhooks/trigger

Use GET https://usable.dev/api/docs for exact request schemas and route authentication. Some webhook management routes are dashboard/session-oriented; do not assume PAT support.

Select events narrowly

For each selected event, define:

• the business action;
• required payload fields;
• deduplication identity;
• whether order matters;
• deletion handling;
• retry behavior;
• data retention.

Broad subscriptions increase data disclosure, noise, and retry load.

Configure receiver authentication

Use the strongest released verification option available. If custom auth headers are supported:

• use a dedicated random credential;
• store it in a secret manager;
• never include it in documentation or logs;
• validate it at the receiver;
• rotate it after exposure or on schedule;
• test the replacement before retiring the old value.

Roll out safely

1. Start with a staging receiver.
2. Test every selected event.
3. Confirm manual tests cannot trigger production side effects.
4. Verify authentication failures are rejected.
5. Confirm duplicate and out-of-order handling.
6. Measure acknowledgment latency.
7. Move to production after review.
8. Monitor the first real deliveries.

Update or disable

Before changing URL, events, or authentication, review dependent workflows and coordinate credential rotation. Avoid overlapping configurations that create duplicate side effects. Disable stale webhooks promptly and delete only after confirming no workflow relies on them.

Common failures

Target URL is rejected

Use an externally reachable HTTPS URL. Released safety guidance blocks insecure, localhost, private-range, and redirect-based SSRF destinations.

Webhook saves but receives nothing

Check enabled state, selected events, workspace, target reachability, and receiver authentication.

Receiver returns 401 or 403

The configured header and receiver secret may differ. Rotate deliberately; do not paste secrets into logs or support threads.

A read-only user cannot configure it

Webhook configuration is a workspace-management action. Ask an authorized workspace owner or administrator to review it.

Related pages

• Webhook events and payloads
• Test and troubleshoot webhooks
• Build a secure and reliable webhook receiver
• API resource directory and OpenAPI