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

1. Open a saved tool and click Deploy.

2. Select Webhooks and copy the webhook URL. The generated URL follows this format:

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

3. Create an API key. The key runs tools with your own access, so use an account that can run only the tools the external service needs. The key in the webhook URL is a secret.

4. Add the URL to the service’s webhook settings.

5. Select the events that should trigger the tool.

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:

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" } }
  }'

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.

Authenticate webhook requests

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

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

Provider pattern	Request	Response
Slack or monday.com	Body with a string challenge	Echoes { "challenge": "..." }
Generic	Body with type: "verification" and verification_token	Echoes { "verification_token": "..." }
Meta or WhatsApp	hub.mode=subscribe and hub.challenge in the query	Echoes hub.challenge as text
Microsoft Graph	validationToken in the query	Echoes the token as text
Generic or Nylas	GET with challenge in the query	Echoes the challenge as text

A request that matches a challenge pattern never executes the tool.

GET requests only perform challenge verification. They never execute a tool.

Security

• Treat webhook URLs as secrets and rotate the associated API key if a URL is exposed.
• Use a key whose owner can run only the tools the service needs. Service-account keys cannot start incoming webhooks.
• Filter the provider event type in the tool when several event types share one endpoint.

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. After execution finishes, superglue sends the run ID, success state, output or error, and file metadata to that URL.

Both examples are available from Deploy → Webhooks.

FAQ

Does superglue verify provider signatures?

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