secutils-dev/secutils/webhooks

Secutils.dev: Webhooks (Responders)

A responder is a Secutils-hosted HTTP endpoint on the user's randomly assigned subdomain (https://<handle>.webhooks.secutils.dev/<path>). Each responder owns one path, one HTTP method (or ANY), a default status code, headers, and body. Advanced settings can attach a JavaScript script that runs inside a restricted Deno sandbox for every incoming request and can override the status, headers, or body, proxy the request to a real upstream, or render dynamic HTML.

Captured request history (up to requestsToTrack) is available through the _history endpoint and the UI grid, so a responder also works as a lightweight HTTP traffic inspector. The human-readable guide lives at <https://secutils.dev/docs/guides/webhooks> and the full API reference at <https://secutils.dev/api-docs/openapi.json>.

Endpoints (tag: webhooks)

The list returns ResponderSummary items. They omit the body, headers, script, and secrets settings. Each item has settingsSize (serialized settings size in bytes) and stats (requestCount and lastRequestedAt for the retained request history). To read the full settings, use GET /api/webhooks/responders/{responder_id}.

Authentication

Two equivalent options:

1. Session cookie (browser flow): authenticate through Kratos at

https://secutils.dev/signin and reuse the resulting ory_kratos_session cookie on every API call.

1. API key (recommended for scripts and agents): create one in

Settings → Security → Manage API keys (see the secutils-api-keys skill), then send it as Authorization: Bearer su_ak_<token>. API keys work without cookies and can authenticate every non-API-key-management endpoint.

Create-responder payload

POST /api/webhooks/responders accepts RespondersCreateParams with the following shape (camelCase JSON):

{
  "name": "my-responder",
  "location": { "pathType": "=", "path": "/my-hook", "subdomainPrefix": null },
  "method": "ANY",
  "enabled": true,
  "settings": {
    "requestsToTrack": 10,
    "statusCode": 200,
    "body": "Hello",
    "headers": [["content-type", "text/plain"]],
    "script": null,
    "secrets": "none"
  },
  "tagIds": []
}

Field notes:

• location.pathType is "=" (exact match), "^" (prefix match), or

"*" (any sub-path).

• location.subdomainPrefix is optional and lets a single user own

multiple subdomains under their handle.

• method is one of GET, POST, PUT, PATCH, DELETE, HEAD,

OPTIONS, CONNECT, TRACE, or ANY.

• settings.requestsToTrack is the rolling history depth (0 disables

capture).

• settings.headers is an array of two-string tuples, not an object, to

preserve duplicate header names and ordering.

• settings.script is the JS body (without an outer IIFE wrapper, the

runtime adds one). See the secutils-deno-runtime skill for the sandbox API surface and the context shape available to the script.

• settings.secrets is "none", "all", or { "selected": [<secret_id>] }

and controls what context.secrets.* exposes (see the secutils-secrets skill).

The full response is the created Responder including its server-assigned id, createdAt, updatedAt, and the absolute live URL the responder serves.

Example flow (curl)

# Create a JSON-mock responder
RESPONDER=$(curl -sX POST https://secutils.dev/api/webhooks/responders \
  -H "Authorization: Bearer $SECUTILS_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "json-mock",
    "location": { "pathType": "=", "path": "/orders/123" },
    "method": "GET",
    "enabled": true,
    "settings": {
      "requestsToTrack": 5,
      "statusCode": 200,
      "headers": [["content-type", "application/json"]],
      "body": "{\"status\":\"shipped\"}",
      "secrets": "none"
    },
    "tagIds": []
  }')
echo "$RESPONDER" | jq -r '.url'   # the public webhook URL
 
# Read tracked requests
ID=$(echo "$RESPONDER" | jq -r '.id')
curl -s -H "Authorization: Bearer $SECUTILS_API_KEY" \
  "https://secutils.dev/api/webhooks/responders/$ID/_history" | jq

Script-powered responders

When settings.script is set, the body and headers in settings become the default response and the script can override them per request by returning a ScriptResult:

interface ScriptResult {
  statusCode?: number;
  headers?: Record<string, string>;
  body?: Uint8Array | string | object;
  skipRequest?: boolean;
  trackResponse?: boolean;
}

The script receives a context global with the request method, path, parsed headers, parsed query, raw body bytes, and decrypted secrets. The full context interface, body auto-conversion table, and the Deno.core.ops.op_proxy_request() API for safely forwarding requests upstream are documented in the secutils-deno-runtime skill and in https://secutils.dev/docs/guides/webhooks#annex-responder-script-examples.

Caveats

• Responder URLs are public by design. There is no built-in auth wall.

The dynamic-script section of the human guide includes self-contained HTTP Basic and cookie-session patterns that the script can apply when needed.

• The script body must not exceed roughly 50 KB. Reusable helpers should

live in a user script (see the secutils-user-scripts skill) and be imported through the Workspace UI; the API stores the inlined, fully-expanded body.

• Setting settings.body together with a script that always returns a

full ScriptResult is fine but wasteful: the static default is only used when the script returns null. Returning null keeps the default response intact, which is the pattern used by the auth-gate examples.

• Deleting a responder also deletes its captured request history. There

is no soft delete.

See also

• Human-readable guide: <https://secutils.dev/docs/guides/webhooks>
• Sandbox API reference: <https://secutils.dev/docs/guides/platform/deno_runtime>
• OpenAPI: <https://secutils.dev/api-docs/openapi.json>