Skip to content

Incoming Webhooks

Incoming webhooks let Stripe, GitHub, Shopify, and other HTTP services start a saved tool. The JSON request body becomes the tool input, and superglue returns immediately while the tool runs in the background.

Set up an incoming webhook

Section titled “Set up an incoming webhook”

  1. Copy the webhook URL

    Open a saved tool, click Deploy, and select Webhooks. The generated URL follows this format:

    https://api.superglue.cloud/v1/hooks/{toolId}?token={apiKey}

  2. Create a restricted API key

    Create an API key and grant it access only to the tools the external service should be able to execute. The key in the webhook URL is a secret.

  3. Configure the external service

    Add the URL to the service’s webhook settings and select the events that should trigger the tool.

  4. Design the tool for the payload

    The request body is passed through unchanged. For example, this request makes data.object.email available to the tool input:

    Terminal window
    curl -X POST "https://api.superglue.cloud/v1/hooks/handle-customer?token=$SUPERGLUE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "id": "evt_1234",
        "type": "customer.created",
        "data": { "object": { "email": "user@example.com" } }
      }'

  5. Review the run

    A valid trigger returns 202 Accepted with the runId, toolId, and an accepted status. The run appears with the webhook request source in Runs and under Recent webhook requests for the tool.

Authentication

Section titled “Authentication”

Webhook requests support either an API key in the token query parameter or the standard header:

Authorization: Bearer YOUR_API_KEY

Query authentication is useful for providers that cannot set custom headers. Header authentication avoids placing the key in a URL. In either case, the key must be allowed to execute the requested tool.

Challenge verification

Section titled “Challenge verification”

The endpoint handles several common provider verification flows before starting a tool:

Provider pattern Request Response
Slack or monday.com POST body with challenge Echoes { "challenge": "..." }
Meta or WhatsApp GET with hub.mode=subscribe and hub.challenge Echoes hub.challenge as text
Microsoft Graph GET with validationToken Echoes the token as text
Generic or Nylas GET with challenge Echoes the challenge as text

GET requests only perform challenge verification; they never execute a tool.

Security

Section titled “Security”
  • Treat webhook URLs as secrets and rotate the associated API key if a URL is exposed.
  • Use a restricted API key scoped to the receiving tool.
  • superglue authenticates the request but does not validate provider-specific HMAC signatures. Put a signature-verifying proxy in front of the webhook when a provider requires cryptographic verification.
  • Filter the provider event type in the tool when several event types share one endpoint.

Incoming versus completion webhooks

Section titled “Incoming versus completion webhooks”

An incoming webhook starts a tool through /v1/hooks/{toolId}. A completion webhook is different: pass options.webhookUrl when running a tool and superglue sends the run ID, success state, output or error, and file metadata to that URL after execution finishes. Both examples are available from Deploy → Webhooks.