Incoming Webhooks

Trigger tools from external services like Stripe, GitHub, Shopify, or any system that can send HTTP webhooks. When an external service sends a webhook, superglue executes your tool with the webhook payload as input.

How it works

When you enable webhooks for a tool, superglue provides a unique webhook URL:

POST https://api.superglue.ai/v1/hooks/{toolId}?token={your_api_key}

Using development mode

To execute webhooks against development/sandbox system credentials, add the mode parameter:

POST https://api.superglue.ai/v1/hooks/{toolId}?token={your_api_key}&mode=dev

This is useful for testing webhook integrations with sandbox environments before going live.

External services send HTTP POST requests to this URL. The request body becomes the tool’s input payload, and superglue executes the tool asynchronously.

Setting up a webhook

Get your webhook URL

Your webhook URL follows this pattern:
```
https://api.superglue.ai/v1/hooks/{toolId}?token={your_api_key}
```
Replace {toolId} with your tool’s ID and {your_api_key} with a valid API key. You can create API keys at https://app.superglue.cloud/api-keys.
Configure the external service

Add the webhook URL to your external service (Stripe, GitHub, etc.). Most services have a webhooks section in their dashboard.
Design your tool for webhook payloads

Your tool receives the raw webhook payload as input. Design your steps to extract the data you need:
```
// Example: Stripe webhook payload
{
  "id": "evt_1234",
  "type": "customer.created",
  "data": {
    "object": {
      "id": "cus_abc123",
      "email": "user@example.com"
    }
  }
}
```
Use template expressions to access nested fields: <<(sourceData) => sourceData.data.object.email>>

Webhook behavior

Asynchronous execution: Returns 202 Accepted immediately, executes the tool in the background
Run tracking: Each webhook trigger creates a run record you can view in the dashboard
Request source: Runs triggered via webhook are labeled with source WEBHOOK in the runs table

Example: Stripe webhook integration

Build a tool that handles Stripe events and syncs customer data to your CRM:

// Tool configuration for handling Stripe customer.created events
{
  id: "handle-stripe-customer",
  steps: [
    {
      id: "addToMailchimp",
      config: {
        systemId: "mailchimp",
        method: "POST",
        url: "https://api.mailchimp.com/3.0/lists/{list_id}/members",
        body: {
          email_address: "<<(sourceData) => sourceData.data.object.email>>",
          status: "subscribed"
        }
      }
    }
  ]
}

Webhook URL: https://api.superglue.ai/v1/hooks/handle-stripe-customer?token={your_api_key}

Example: GitHub webhook integration

Trigger a deployment tool when code is pushed to your repository:

// Tool that deploys when code is pushed to main
{
  id: "deploy-on-push",
  steps: [
    {
      id: "triggerDeploy",
      config: {
        systemId: "vercel",
        method: "POST",
        url: "https://api.vercel.com/v13/deployments",
        body: {
          name: "my-app",
          gitSource: {
            type: "github",
            ref: "<<(sourceData) => sourceData.ref>>",
            repoId: "<<(sourceData) => sourceData.repository.id>>"
          }
        }
      }
    }
  ]
}

Security considerations

Use HTTPS: Always use HTTPS webhook URLs
Restricted API keys: Use API keys that only have permission to execute specific tools
Validate signatures: If the source service provides webhook signatures (e.g., Stripe’s stripe-signature header), validate them in your tool logic
Monitor activity: Regularly review the runs dashboard for unexpected webhook activity
Rotate keys: Periodically rotate API keys used for webhooks

Filtering webhook events

Many services send multiple event types to the same webhook URL. Filter events in your tool using conditional logic:

// Only process customer.created events from Stripe
{
  outputTransform: `(sourceData) => {
    if (sourceData.type !== 'customer.created') {
      return { skipped: true, reason: 'Event type not handled' };
    }
    return sourceData.addToMailchimp;
  }`;
}

Tool chaining

You can chain tools together so that one tool automatically triggers another when it completes. This is useful for building multi-step workflows where the output of one tool becomes the input of the next.

How it works

When running a tool via the API, use the special tool:{toolId} format for the webhookUrl option instead of an HTTP URL:

curl -X POST "https://api.superglue.ai/v1/tools/fetch-orders/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "since": "2025-01-01"
    },
    "options": {
      "async": true,
      "webhookUrl": "tool:process-orders"
    }
  }'

When fetch-orders completes:

Its output data becomes the input payload for process-orders
process-orders is triggered automatically
The chained run has requestSource: "tool-chain"

Viewing chained runs

You can filter runs by request source to see tool chain executions:

curl "https://api.superglue.ai/v1/runs?requestSources=tool-chain" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example: ETL pipeline

Build a data pipeline where each stage triggers the next:

extract-data → fetches raw data from source API
transform-data → cleans and reshapes the data
load-data → inserts into destination database

# Start the pipeline - each tool chains to the next
curl -X POST "https://api.superglue.ai/v1/tools/extract-data/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": { "table": "customers" },
    "options": {
      "async": true,
      "webhookUrl": "tool:transform-data"
    }
  }'

Configure transform-data to chain to load-data in its tool configuration or pass it at runtime.