Skip to main content
Enterprise Feature — Incoming webhooks are available on superglue Enterprise plans. Contact us to learn more.
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}
Example with real values:https://api.superglue.ai/v1/hooks/handle-stripe-customer?token=a1b2c3d4-e5f6-7890-abcd-ef1234567890Replace with your actual tool ID (e.g., handle-stripe-customer) and with your API key UUID. Don’t include the curly braces {} — they’re just placeholders.
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

1

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.
2

Configure the external service

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

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

Webhook URLs include your API token. Treat them as secrets.
  • 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;
  }`
}