Inbound Webhooks

Inbound webhooks let external systems push events into Sprigr Teams. Each webhook gets a unique URL that accepts HTTP POST requests, processes the incoming payload, and routes it to the right destination — whether that is a specific agent, a workflow, a custom script, or a Sprigr search index.

Webhooks are the bridge between your existing systems and Sprigr Teams. Any system that can send HTTP requests (monitoring tools, CRMs, e-commerce platforms, form builders) can trigger actions in your workspace.

How webhooks work

1. You create a webhook in Sprigr Teams, which generates a unique URL
2. You configure your external system to send HTTP POST requests to that URL
3. When an event occurs, the external system sends a JSON payload to the webhook URL
4. Sprigr Teams verifies the request (if authentication is configured) and routes the payload to the configured destination

Each webhook can be configured with authentication, a destination type, a response mode, and an optional callback URL.

The webhook URL

Every webhook gets a unique URL in this format:

https://api.team.sprigr.com/webhook/hook/{token}

The {token} is a secret generated when the webhook is created — treat the full URL as a credential. Requests must be HTTP POST with a JSON body:

• An unknown token, or a webhook that has been paused or deleted, returns 404
• A body that is not valid JSON returns 400

Destination types

When creating a webhook, you choose where incoming payloads should be routed.

Agent

Send to a specific agent. The webhook payload is delivered as a message to the selected agent. The message text is the payload (or the fields your payload transform maps to it), and the full raw payload is attached as message metadata, so the agent can inspect every field. The agent can then process the information and take action using its tools and integrations.

Best for: Alerts, notifications, and events that need an intelligent response. For example, a monitoring alert that the agent should diagnose and triage.

Configuration:

• Select the destination agent
• Optionally target a specific conversation (via the API), so repeat events land in one thread instead of starting new conversations

Workflow

Trigger a workflow. The webhook payload is passed as input to the selected workflow, starting a new execution. The payload data is available to all steps in the workflow.

Best for: Structured, multi-step processes that should kick off when an event happens. For example, starting an onboarding workflow when your HR system sends a “new employee” event.

Configuration:

• Select the team, then enter the workflow slug or ID

Workflow webhooks always respond immediately with the new execution’s ID — the workflow itself runs in the background.

Code

Run a webhook script. The payload is passed to a script from your script library, written in JavaScript or Python. The script runs in an isolated sandbox and can validate, transform, or act on the payload — for example, calling an external API or writing a file to the agent’s workspace.

Best for: Custom validation, data transformation, or side effects that do not need an agent. See Webhook Scripts for details.

Configuration:

• Select a script from your webhook script library
• Select a sandbox agent — the script runs in that agent’s isolated execution environment
• Use sync response mode so the caller receives the script’s output

Sprigr

Write to a search index. The webhook payload is stored as an object in a Sprigr search index. This is useful for feeding data into your agents’ searchable knowledge without manual uploads.

Best for: Continuous data ingestion. For example, receiving product updates from your e-commerce platform and keeping a product index current.

Configuration:

• Enter the destination index name
• Optionally provide an object ID path — a dot-path (like data.id) that extracts a stable object ID from each payload, so repeat events update the same object instead of creating duplicates. If left empty, an ID is auto-generated per event.

Authentication types

You can secure your webhooks with authentication to ensure only authorised systems can send events.

Type	Description
None	No authentication. Any system with the URL can send events. Only use this for testing or internal systems.
HMAC SHA-256	The sender signs each request body with a shared secret and puts the hex signature in a header (default X-Webhook-Signature, configurable). Sprigr Teams accepts both a raw hex digest and the sha256= prefixed format used by GitHub- and Stripe-style webhooks. This is the most common method and is supported by most webhook providers.
Bearer token	The sender includes the token in the Authorization: Bearer header. Sprigr Teams checks it against the stored value. Simple and widely supported.

Requests that fail verification are rejected with 401 and are not routed anywhere.

Tip

Always use authentication for production webhooks. Without it, anyone who discovers the URL can send fake events to your workspace.

Response modes

Control how Sprigr Teams responds to incoming webhook requests:

• Async (acknowledge immediately) — Sprigr Teams responds with 202 Accepted and processes the payload in the background. This is the default. The sending system does not wait for processing to complete.
• Sync (wait for result) — Sprigr Teams processes the payload and returns the result in the HTTP response. Use this when the sender needs an answer, or for code-destination webhooks where the caller should receive the script output.

Two destinations respond immediately regardless of mode: workflow webhooks return the execution ID as soon as the workflow starts, and Sprigr webhooks return the indexed object ID.

Note

Sync mode is bounded by the platform’s request timeout. For long-running processing, use async mode and have the agent or workflow send results through another channel (email, Slack, etc.), or configure a callback URL.

Callback URLs

For async webhooks, you can configure an optional callback URL. When processing finishes, Sprigr Teams POSTs the result to that URL:

{
  "webhookEndpointId": "whk_...",
  "status": "completed",
  "result": { "...": "..." },
  "completedAt": "2026-07-08T00:00:00.000Z"
}

The status is completed or failed. If the webhook has an auth secret configured, the callback body is HMAC SHA-256 signed and the signature is sent in the X-Webhook-Signature header (sha256= prefixed), so your receiving system can verify it came from Sprigr Teams.

Payload transforms

By default, the message text delivered to an agent is the payload JSON (truncated to 500 characters), with the full payload attached as metadata. If your payloads are large or awkwardly shaped, you can attach a transform to the webhook: a dot-path field mapping that pulls values out of the payload into the message text, metadata, and sender ID. For example, mapping text to data.description makes the message text the value at payload.data.description.

Transforms are set when creating the webhook through the API or by asking an agent — the portal shows a webhook’s transform on its detail page.

Creating a webhook

1. Navigate to the Webhooks page

   Sign in to team.sprigr.com and click Webhooks in the sidebar.

2. Click “New Webhook”

   Click the New Webhook button to open the creation form.

3. Enter a name

   Give the webhook a descriptive name like “New Job Notifications” or “Payment Events”. This helps your team identify the webhook later.

4. Select a destination type

   Choose where incoming payloads should be routed: agent, workflow, code, or sprigr. Then configure the destination — for example, select which agent should receive the messages.

5. Configure authentication

   Choose an authentication method (None, HMAC SHA-256, or Bearer Token) and enter the secret. You can click Generate to auto-create a random signing secret. For HMAC, you can also change the signature header name (default X-Webhook-Signature).

6. Select a response mode

   Choose Async (return 202 immediately) or Sync (wait for the result). Async is the most common choice for agent destinations; use sync for code destinations.

7. Optionally add a callback URL

   For async webhooks, enter a callback URL if your system needs to receive the processing result.

8. Click “Create Webhook”

   The webhook is created and a unique URL is generated. Copy this URL and configure it in the external system that will be sending events.

Try asking your agent

“Set up a webhook that accepts job notifications from our CRM and passes them to the Scheduling agent for processing.”

“Create a webhook endpoint for Stripe payment events that updates our Bookkeeper agent when invoices are paid.”

Once created, you can view the webhook detail page with its configuration, URL, and trigger history.

Pausing a webhook

From the webhook detail page you can pause a webhook without deleting it. While paused, requests to its URL return 404 and nothing is routed. Resume it at any time — the URL stays the same.

Rate and usage limits

Webhook ingestion is rate limited per webhook according to your organisation’s plan. When the limit is exceeded, the sender receives 429 with a retryAfter value (in seconds). If your organisation’s monthly usage limit is reached, webhooks return 402 until the plan is upgraded or overage billing is enabled.

Trigger history

Every webhook keeps a log of its most recent 100 events. You can also click Test on the detail page to send a test payload through the full pipeline. Each entry records:

• Timestamp, processing duration, and source IP of the sender
• Whether processing succeeded or failed, and the HTTP status code returned
• A preview of the request payload and the response body
• The destination it was routed to, and the error message if routing failed

Use the trigger history to verify that your external system is sending events correctly and to debug any issues with payload processing.

Next steps

• Webhook Scripts — Write custom scripts to process webhook payloads.
• Workflows — Trigger workflows from webhook events.
• Knowledge Bases — Feed webhook data into your knowledge bases.