Skip to main content

Documentation Index

Fetch the complete documentation index at: https://supahooks.ar27111994.dev/llms.txt

Use this file to discover all available pages before exploring further.

The customScript input lets you run an inline JavaScript snippet against every captured event before it is written to storage. Use it to normalize payloads from different providers, strip PII, inject debug metadata, or remap fields — all without modifying the sender or adding a separate processing step.

​
How scripts run

Each script executes inside a sandboxed worker thread. The worker is shared for the lifetime of the actor run, so the sandbox is persistent but isolated from the main server process. The runtime enforces a bounded execution timeout and memory ceiling so a runaway script cannot block request handling or exhaust host resources. If a script fails or times out, the error is logged and the webhook capture continues normally — the event is still stored and the sender still receives the configured response.

​
Script context

Your script receives four injected values:
NameTypeDescription
eventobjectThe mutable captured event. Mutate this object to change what gets stored.
reqobjectA read-only snapshot of the incoming request. Changes to this object have no effect.
consoleobjectA safe console with log, warn, error, and debug methods. Output goes to the actor log.
HTTP_STATUSobjectA map of named HTTP status codes for readable comparisons (e.g., HTTP_STATUS.OK === 200).

​
The event object

These fields on event are writable and affect what is stored:
FieldTypeDescription
bodystring | objectThe request body. Replace or mutate this to change the stored payload.
headersobjectThe request headers as a key-value map. Add, remove, or overwrite individual headers.
contentTypestringThe Content-Type value from the request.
statusCodeintegerThe HTTP status code the actor will return to the sender. You can override this from a script.

​
The req object

req is a reduced, read-only snapshot of the incoming request — not the live request object. It gives your script access to query parameters, the original URL, and the remote IP for use in transformation logic. You cannot call methods on req or modify it; changes have no effect.

​
What scripts cannot do

Scripts run in a restricted sandbox. The following are not available:
  • process — no access to the Node.js process object or environment variables
  • require / import — no module loading
  • Filesystem APIs — no fs, path, or similar
  • Network APIs — no fetch, http, https, or XMLHttpRequest
  • eval() and Function() — code generation from strings is disabled
Scripts that attempt to access restricted globals will throw a ReferenceError at runtime. The error is logged and the capture continues, but the transformation will not be applied.

​
Common use cases

​
1. Parse and normalize a JSON body

When enableJSONParsing is off or the body arrives as a raw string, parse it yourself and add a debug flag: 
if (event.contentType === 'application/json') {
  const body = typeof event.body === 'string' ? JSON.parse(event.body) : event.body;
  event.body = { ...body, normalized: true, source: 'webhook-debugger' };
}

​
2. Strip PII before storage

Remove sensitive fields from the payload so they are never written to the dataset: 
if (event.body && typeof event.body === 'object') {
  const { email, phone, ssn, ...safe } = event.body;
  event.body = safe;
}

​
3. Add debug metadata

Inject custom fields for easier filtering in /logs queries: 
const provider = event.headers['x-webhook-provider'] || 'unknown';
event.body = {
  ...event.body,
  _debug: {
    capturedAt: new Date().toISOString(),
    provider,
    remoteIp: req.ip,
  },
};

​
4. Remap fields for a downstream schema

Flatten or rename fields before the event is forwarded or stored: 
if (event.body && event.body.data && event.body.data.object) {
  const obj = event.body.data.object;
  event.body = {
    id: obj.id,
    type: event.body.type,
    amount: obj.amount,
    currency: obj.currency,
    created: obj.created,
  };
}

​
Adjusting worker memory

If your scripts process large payloads and hit memory limits, you can raise the worker heap ceilings with two environment variables:
VariableRangeDefaultDescription
CUSTOM_SCRIPT_WORKER_MAX_OLD_GENERATION_MB16–25632Old-generation heap ceiling for the script worker, in MB.
CUSTOM_SCRIPT_WORKER_MAX_YOUNG_GENERATION_MB8–12816Young-generation (semi-space) heap ceiling, in MB.
See Environment variables for how to set these in a local .env or Docker run command.
Scripts share a single worker sandbox for the lifetime of the actor run. Complex scripts or scripts that retain references to large objects can cause memory pressure over time. Test new scripts against low traffic first before deploying to a high-volume endpoint.
Use console.log() inside your script to debug transformation logic. Output appears in the actor log alongside normal request processing messages.