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 and click Webhook Scripts in the sidebar.

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, 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:

• Exit code 0 means success; anything else marks the run as failed
• stdout and stderr are captured

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 allowed, so scripts can call external APIs
• Scripts can read and write files in the sandbox agent’s workspace; files written there persist and are visible to the agent
• Execution time is bounded by the sandbox; 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

If your script exits with a non-zero code or fails to run (for example, the referenced script was deleted):

1. The event is recorded as an error in the webhook’s trigger history, with the error detail
2. The caller receives an error response (502 if execution could not complete)
3. In sync mode, a script that ran but failed still returns its stdout, stderr, and exitCode, so the caller can see what went wrong

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.