Webhook Scripts

Webhook scripts let you run custom code whenever a webhook fires. A script is a JavaScript or Python program stored in your workspace’s script library; when an inbound webhook with the code destination receives an event, the script runs in an isolated sandbox with the payload as its input. Scripts can validate and transform data, call external APIs, and return output to the calling system.

When to use scripts

Use a webhook script when you need to:

• Transform data — Reshape a payload from one format to another and return the result to the caller
• Validate events — Check that a payload is well-formed and return a meaningful error to the sender if it is not
• Call external APIs — Forward or enrich events by calling another service directly from the script
• Run deterministic logic — Handle events with plain code where an agent’s judgement is not needed

If you want every incoming payload to reach an agent, a workflow, or a search index, you do not need a script — use the agent, workflow, or Sprigr destination type directly when creating the webhook.

The script library

Scripts live in their own library, separate from any single webhook, so one script can be shared by several webhooks.

1. Navigate to the Webhook Scripts page

   Sign in to team.sprigr.com, click Webhooks in the sidebar, then click the Scripts link at the top of the Webhooks page. Webhook scripts do not have their own sidebar entry; the Scripts item in the sidebar is the separate, workflow-backed Scripts feature.

2. Click “New Script”

   Enter a name, choose the language (JavaScript or Python), and optionally add a description.

3. Write the code

   Use the built-in code editor, which has syntax highlighting for both languages. You can also click AI (or press Cmd+K) to describe what the script should do and have the code generated or modified for you.

4. Save

   Click Create Script (or press Cmd+S in the editor when editing later). The script is now available to select as a webhook destination.

Editing a script updates every webhook that references it. Deleting a script breaks any webhooks still using it (they may keep serving a cached copy briefly, then fail with 502), so reassign those webhooks first.

How scripts receive the payload

The incoming webhook body is provided to your script as the WEBHOOK_PAYLOAD environment variable, containing the raw JSON string:

JavaScript

const payload = JSON.parse(process.env.WEBHOOK_PAYLOAD);
console.log(payload);

Python

import os, json

payload = json.loads(os.environ["WEBHOOK_PAYLOAD"])
print(payload)

The request headers and query string are not passed to the script — only the JSON body.

Script output

Scripts communicate through standard output and their exit code:

• stdout, stderr, and the exit code are captured and returned
• A non-zero exit code does not change the HTTP status today and the trigger history still records the event as a success, so callers must inspect exitCode in the body rather than rely on the status code

When the webhook’s response mode is sync, the caller receives the script result in the HTTP response:

{
  "stdout": "...",
  "stderr": "",
  "exitCode": 0
}

Print JSON to stdout if the calling system needs structured data back. Use sync response mode for code-destination webhooks so the caller receives this output.

Note

Webhook scripts do not route events onwards by returning special values. If an event should reach an agent or start a workflow, point the webhook’s destination at that agent or workflow directly, or have the script call an external endpoint itself.

Connecting a script to a webhook

When creating a webhook (see Inbound Webhooks), choose code as the destination type, then:

1. Select the script from the dropdown
2. Select a sandbox agent — the script executes inside that agent’s isolated sandbox, so it shares the agent’s workspace files
3. Set the response mode to sync

Example script

Here is a JavaScript example that validates an incoming order event and returns a normalised summary to the caller:

const payload = JSON.parse(process.env.WEBHOOK_PAYLOAD);

const amount = parseFloat(payload.order_total);
if (isNaN(amount)) {
  console.error("Invalid order_total: " + payload.order_total);
  process.exit(1);
}

const summary = {
  orderId: payload.id || "unknown",
  customer: payload.customer_email || "unknown",
  total: amount,
  highValue: amount >= 500,
};

console.log(JSON.stringify(summary));

Try asking your agent

“Write a webhook script that parses incoming order events, rejects any payload without an order_total, and prints a normalised JSON summary.”

Execution environment

• Scripts run as Node.js (JavaScript) or Python 3 in an isolated sandbox container, scoped to the selected agent and your organisation — other organisations’ code and data are never reachable
• Outbound HTTP requests are not blocked by any script-level policy, so scripts can call external APIs
• Scripts run from a temporary directory. Only files written to absolute paths under /workspace/{companyId}/{agentId} persist and are visible to the agent; relative-path writes land in the temporary directory and are discarded when the run ends
• No per-script time limit is applied on this path today, and the caller waits for the whole run in sync mode; keep scripts short-running, and use an agent or workflow destination for heavy processing

Testing scripts

Before relying on a webhook script in production:

1. Use the webhook’s Test button — On the webhook detail page, click Test to send a test payload through the full pipeline, including your script. The result appears inline and in the trigger history.
2. Send a real payload — Use a tool like cURL or Postman to POST a representative payload to the webhook URL, then check the trigger history to see the script’s output or error.

Tip

Start with a script that just parses and prints the payload, then run a test event and read the output in the trigger history. Once you can see exactly what data you receive, add the real logic.

Error handling

There are two failure shapes:

1. The script could not run at all (for example, the referenced script was deleted, or the sandbox was unreachable). The event is recorded as an error in the webhook’s trigger history with the error detail, and the caller receives 502.
2. The script ran but exited non-zero. The caller still receives HTTP 200 with stdout, stderr, and the non-zero exitCode, and the trigger history records the event as a success. Treat exitCode as the source of truth on the caller’s side.

Handle expected bad input inside the script and exit non-zero with a clear message on stderr:

import os, json, sys

try:
    payload = json.loads(os.environ["WEBHOOK_PAYLOAD"])
except (KeyError, json.JSONDecodeError) as err:
    print(f"Bad payload: {err}", file=sys.stderr)
    sys.exit(1)

Next steps

• Inbound Webhooks — Set up the webhook that will call your script.
• Workflows — Use a workflow destination for multi-step processing.
• Creating Agents — Create the agents whose sandboxes your scripts run in.