Test and troubleshoot webhooks

Usable can manually send fragment webhook events using an existing fragment without creating, updating, or deleting it. Use this flow before enabling downstream production side effects.

Prerequisites

You need access to the workspace and fragment, plus at least one active webhook subscribed to a supported fragment event.

Test from a fragment

1. Open the workspace's fragment detail page.
2. Open the Actions menu.
3. Select Test Webhooks.
4. Choose Fragment Created, Fragment Updated, or Fragment Deleted.
5. Review the delivery summary.
6. Inspect the request at your development receiver.
7. Confirm x-usable-test-trigger: true is present.
8. Verify authentication, payload parsing, and response time.

The test uses existing fragment data and should not mutate the fragment.

Test through REST

The released route is:

POST /api/workspaces/{workspaceId}/webhooks/trigger

A public request intent is:

{
  "fragmentId": "<fragment-id>",
  "eventType": "fragment.updated"
}

Use the deployed OpenAPI document for exact authentication and schema. The route can return triggered, successful, and failed counts plus per-webhook status and timing.

Interpret results

• All succeeded — every selected active receiver acknowledged successfully.
• Partial failure — inspect each failed target independently.
• All failed — check shared configuration such as network, URL policy, or credentials.
• No webhook triggered — confirm active state and event subscription.

A successful HTTP delivery means the receiver acknowledged the request; it does not prove downstream processing completed.

Test safely

At the receiver:

if test header is true:
  validate and log redacted metadata
  skip production side effects
  acknowledge
else:
  enqueue normal processing
  acknowledge

Do not use the test header as authentication, and do not exempt test requests from all abuse controls.

Common failures

Test Webhooks is disabled

No active webhook is subscribed to a supported fragment event, or the caller lacks access. Review workspace settings and selected events.

Endpoint is unreachable

Confirm public HTTPS reachability, DNS, certificate validity, firewall policy, and that redirects do not lead to blocked/private destinations.

Authentication fails

Compare configured and receiver credentials without logging either value. Rotate if uncertain.

Receiver cannot parse payload

Validate event type and required fields. Log a redacted test payload in development, compare with the released example, and tolerate additive fields.

Receiver is slow

Acknowledge quickly and move work to a queue. Released public guidance notes a 30-second delivery timeout, but production receivers should respond much sooner.

Duplicate side effects occur

Use a stable event/resource identity and an idempotency store. Manual tests and retries can repeat equivalent events.

Updates appear out of order

Compare event time or canonical resource state before applying a stale update.

Production troubleshooting record

Capture webhook ID/name, workspace, event type, approximate time, HTTP status, response duration, test-versus-live indicator, retry count, and a redacted error. Never include auth headers, full private content, or receiver secrets.

Related pages

• Configure a workspace webhook
• Webhook events and payloads
• Build a secure and reliable webhook receiver
• Requests, responses, pagination, and errors