Webhook Triggers

Webhook triggers start your workflow when an external service sends an HTTP request. Use webhooks to integrate with any service that supports them.

Setting Up a Webhook

Create the Trigger

1. Add a Webhook trigger to your workflow
2. A unique URL is generated automatically
3. Copy this URL to configure in the external service

Webhook URL Format

https://api.specway.com/webhooks/{workflow_id}

Each workflow gets a unique, permanent URL.

Configuration Options

HTTP Methods

Choose which methods to accept:

• POST (default) - Most common for webhooks
• GET - For simple triggers
• PUT - For update events
• DELETE - For deletion events
• All - Accept any method

Authentication

Secure your webhook endpoint:

None - Open endpoint (not recommended for production)

API Key - Require a key in the header

X-API-Key: your-secret-key

Bearer Token - Standard authorization header

Authorization: Bearer your-token

Signature Verification - Verify request signatures (service-specific)

Response

Configure what the webhook returns:

Immediate - Returns 200 OK immediately, workflow runs async

Wait for Completion - Returns workflow output (slower, but useful for sync integrations)

Accessing Webhook Data

The trigger provides all request data:

Request Body

{{trigger.body}}
{{trigger.body.event}}
{{trigger.body.data.id}}

Headers

{{trigger.headers}}
{{trigger.headers['content-type']}}
{{trigger.headers.authorization}}

Query Parameters

{{trigger.query}}
{{trigger.query.page}}
{{trigger.query.filter}}

Request Metadata

{{trigger.method}}      // GET, POST, etc.
{{trigger.url}}         // Full request URL
{{trigger.ip}}          // Client IP address

Testing Webhooks

Using the Test Panel

1. Open your workflow
2. Click Test
3. Enter sample JSON payload
4. Click Send Test Request

Using curl

curl -X POST https://api.specway.com/webhooks/abc123 \
  -H "Content-Type: application/json" \
  -d '{"event": "test", "data": {"id": 1}}'

Using External Tools

• Postman - Full-featured API testing
• Insomnia - Lightweight alternative
• Webhook.site - Test incoming webhooks

Common Webhook Sources

GitHub

Events: push, pull_request, issues, etc.

{
  "action": "opened",
  "pull_request": {
    "title": "New feature",
    "user": { "login": "developer" }
  }
}

Stripe

Events: payment_intent.succeeded, customer.created, etc.

{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "amount": 2000,
      "currency": "usd"
    }
  }
}

Slack

Events: message, reaction_added, etc.

{
  "type": "message",
  "text": "Hello world",
  "user": "U123456"
}

Security Best Practices

1. Always use authentication in production
2. Verify signatures when available (GitHub, Stripe)
3. Validate payloads before processing
4. Use HTTPS (enforced by default)
5. Rotate secrets periodically

Troubleshooting

Webhook not triggering

• Verify the URL is correct
• Check authentication headers
• Look at execution logs for errors
• Ensure workflow is activated

Invalid payload

• Check content-type header
• Verify JSON is valid
• Log the raw body to inspect

Timeout errors

• External service may timeout before response
• Use async response mode
• Increase timeout if supported

Next Steps

• Node Types Explained - All trigger types
• Execution Logs - Monitor webhook calls
• Debugging Errors - Fix issues