Webhook Scripts

Webhook scripts let you write custom code to process incoming webhook payloads before they reach an agent or workflow. Scripts can transform data, apply routing logic, filter out irrelevant events, and control what happens next. This gives you full flexibility over how external events are handled in Sprigr Teams.

When to use scripts

Use a webhook script when you need to:

• Transform data — Reshape a payload from one format to another before passing it to an agent
• Route events — Send different event types to different agents or workflows based on the payload content
• Filter events — Ignore events that do not meet certain criteria (for example, only process orders over a certain value)
• Enrich data — Add context to the payload before forwarding it
• Return custom responses — Send a specific response back to the calling system (for sync-mode webhooks)

If you simply want to forward every incoming payload to a single agent or workflow without modification, you do not need a script — use the Agent or Workflow destination type directly.

The code editor

When you select Code as the destination type for a webhook, a built-in code editor opens where you can write your script. The editor supports JavaScript and Python, with syntax highlighting and basic error checking.

Script context

Your script receives the following context variables:

Variable	Type	Description
payload	Object	The parsed JSON body of the incoming HTTP request
headers	Object	The HTTP headers from the incoming request
query	Object	Any query string parameters from the webhook URL
webhookId	String	The unique identifier of this webhook

Return values

What your script returns determines what happens next:

Return value	Behaviour
{ agent: "agent-slug", message: "..." }	Forwards the message to the specified agent
{ workflow: "workflow-slug", input: {...} }	Triggers the specified workflow with the given input
{ response: { status: 200, body: "..." } }	Returns a custom HTTP response to the caller (sync mode)
{ knowledge: { index: "index-name", data: {...} } }	Writes data to a knowledge base index
null or undefined	The event is acknowledged but no further action is taken (effectively filtered out)

Example script

Here is a simple example that routes incoming support tickets to different agents based on the ticket priority:

// Route high-priority tickets to the Senior Support Agent
// and everything else to the General Support Agent

const priority = payload.priority || "normal";
const subject = payload.subject || "No subject";
const customerEmail = payload.customer_email || "unknown";

if (priority === "urgent" || priority === "high") {
  return {
    agent: "senior-support-agent",
    message: `Urgent ticket from ${customerEmail}: ${subject}\n\nDetails: ${JSON.stringify(payload)}`
  };
}

return {
  agent: "general-support-agent",
  message: `New ticket from ${customerEmail}: ${subject}\n\nDetails: ${JSON.stringify(payload)}`
};

Try asking your agent

“Write a webhook script that checks if the incoming payload has a priority field set to ‘urgent’, and if so, routes it to the emergency dispatch workflow instead of the regular queue.”

Testing scripts

Before enabling a webhook with a script in production, test it:

1. Use the editor’s test feature — The code editor includes a “Test” button. Paste a sample payload and click Test to see what the script returns without actually triggering any actions.
2. Send a test event — Use a tool like cURL or Postman to send a test payload to the webhook URL. Check the trigger history to see if the event was processed correctly.

Tip

Start with simple scripts and add complexity as needed. Log the incoming payload to the trigger history first so you can see exactly what data you are working with before writing routing logic.

Error handling

If your script throws an error, the webhook will:

1. Return a 500 status code to the caller
2. Log the error in the trigger history with the error message and stack trace
3. Not forward anything to an agent or workflow

To handle errors gracefully, wrap risky operations in try/catch blocks:

try {
  const amount = parseFloat(payload.order_total);
  if (isNaN(amount)) {
    return { response: { status: 400, body: "Invalid order total" } };
  }
  // Process the order...
} catch (error) {
  return { response: { status: 500, body: "Script error: " + error.message } };
}

Limitations

• Scripts have a maximum execution time of 10 seconds
• Scripts cannot make outbound HTTP requests (use agent integrations for external API calls)
• Scripts run in a sandboxed environment and cannot access the file system or other system resources

Next steps

• Inbound Webhooks — Set up the webhook that will call your script.
• Workflows — Trigger workflows from your webhook scripts.
• Creating Agents — Create the agents that your scripts route events to.