Webhooks Integration: Connect supaguard to Any System
Set up custom webhooks to send supaguard alerts to any HTTP endpoint. Includes payload schema, authentication options, and integration examples.
Webhooks let you connect supaguard to any system that can receive HTTP requests. Use webhooks to integrate with custom dashboards, internal tools, or services we don't have native integrations for.
Quick Setup
Step 1: Identify Your Endpoint
You need an HTTP endpoint that can receive POST requests:
https://your-service.com/webhooks/supaguardStep 2: Add Webhook in supaguard
- Go to Settings → Communications
- Click Add Channel
- Select Webhook
- Configure:
- Name: Descriptive name (e.g., "Internal Dashboard")
- URL: Your endpoint
- Headers: Any required authentication headers
- Click Save
Step 3: Test
Click Send Test to verify the integration works.
Webhook Payload Schema
supaguard sends JSON payloads for different events:
Check Failed
{
"event": "check.failed",
"timestamp": "2024-01-15T10:30:00.000Z",
"check": {
"id": "chk_abc123def456",
"name": "Homepage Load Test",
"url": "https://example.com"
},
"result": {
"id": "res_789xyz",
"status": "failed",
"classification": "critical",
"duration_ms": 5234,
"location": "us-west-1",
"error": "Timeout waiting for element: button[name='Submit']",
"screenshot_url": "https://storage.supaguard.app/screenshots/...",
"trace_url": "https://app.supaguard.com/trace/..."
},
"organization": {
"id": "org_123",
"slug": "acme-corp"
}
}Check Recovered
{
"event": "check.recovered",
"timestamp": "2024-01-15T10:35:00.000Z",
"check": {
"id": "chk_abc123def456",
"name": "Homepage Load Test",
"url": "https://example.com"
},
"result": {
"id": "res_789abc",
"status": "passed",
"duration_ms": 1523,
"location": "us-west-1"
},
"downtime": {
"started_at": "2024-01-15T10:30:00.000Z",
"ended_at": "2024-01-15T10:35:00.000Z",
"duration_seconds": 300
},
"organization": {
"id": "org_123",
"slug": "acme-corp"
}
}Check Degraded
{
"event": "check.degraded",
"timestamp": "2024-01-15T10:30:00.000Z",
"check": {
"id": "chk_abc123def456",
"name": "Homepage Load Test",
"url": "https://example.com"
},
"result": {
"id": "res_789xyz",
"status": "degraded",
"classification": "degraded",
"duration_ms": 8500,
"location": "us-west-1",
"warning": "Page load time exceeded threshold (8.5s > 3s)"
},
"organization": {
"id": "org_123",
"slug": "acme-corp"
}
}Authentication Options
Bearer Token
Authorization: Bearer your-secret-tokenConfigure in supaguard:
- Header Name:
Authorization - Header Value:
Bearer your-secret-token
API Key Header
X-API-Key: your-api-keyConfigure:
- Header Name:
X-API-Key - Header Value:
your-api-key
Basic Auth
Authorization: Basic base64(username:password)Configure:
- Header Name:
Authorization - Header Value:
Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Signature Verification (Advanced)
supaguard includes a signature header for verifying webhook authenticity:
X-supaguard-Signature: sha256=abc123...Verify by computing HMAC-SHA256 of the payload with your webhook secret.
Integration Examples
Microsoft Teams
Create a Teams incoming webhook, then configure supaguard to send to it:
// supaguard will need a transformation layer
// Consider using a middleware like n8n or Zapier
{
"@type": "MessageCard",
"summary": "Check Failed",
"sections": [{
"activityTitle": "supaguard Alert",
"facts": [
{"name": "Check", "value": "Homepage Load Test"},
{"name": "Status", "value": "CRITICAL"}
]
}]
}Discord
Create a Discord webhook and use it directly — Discord accepts standard webhook payloads with embeds:
{
"embeds": [{
"title": "Check Failed: Homepage Load Test",
"color": 15158332,
"fields": [
{"name": "Status", "value": "CRITICAL", "inline": true},
{"name": "Location", "value": "San Francisco", "inline": true}
]
}]
}Custom Dashboard
Receive webhooks and store in your database:
// Express.js example
app.post('/webhooks/supaguard', (req, res) => {
const event = req.body;
if (event.event === 'check.failed') {
db.insert('alerts', {
check_name: event.check.name,
status: event.result.classification,
timestamp: event.timestamp,
error: event.result.error
});
}
res.status(200).send('OK');
});Zapier / n8n / Make
Use these automation platforms to:
- Receive supaguard webhooks
- Transform the payload
- Send to any destination
This enables complex workflows without custom code.
Handling Failures
Retry Behavior
supaguard retries failed webhook deliveries:
- 3 retries with exponential backoff
- Timeouts after 30 seconds
Error Logging
Failed deliveries appear in your supaguard dashboard under Settings → Communications → Delivery History.
Best Practices
- Return 200 quickly — Process asynchronously if needed
- Handle duplicates — Webhooks may retry; use idempotent handling
- Log payloads — Helps debug integration issues
Security Best Practices
Verify Webhook Source
Always verify the X-supaguard-Signature header to ensure requests come from supaguard.
Use HTTPS
Always use HTTPS endpoints. supaguard won't send to HTTP URLs in production.
Restrict IP (Optional)
If your firewall allows, restrict incoming webhooks to supaguard's IP ranges.
Secret Management
Store webhook secrets securely:
- Use environment variables
- Don't commit to version control
- Rotate periodically
Debugging Webhooks
Use Request Bin
Test with a service like webhook.site to inspect payloads.
Check supaguard Logs
View delivery attempts in Settings → Communications → Delivery History.
Verify Endpoint
curl -X POST https://your-endpoint.com/webhooks \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-token" \
-d '{"event": "test"}'Related Resources
- Slack Integration — Native Slack support
- PagerDuty Integration — On-call alerting
- Configuring Alerts — Alert policies
Slack Integration: Get Synthetic Monitoring Alerts in Slack
Set up Slack integration for supaguard alerts. Step-by-step guide to receiving synthetic monitoring notifications in your Slack workspace with formatted messages.
E-Commerce Checkout Monitoring: Catch Revenue-Killing Bugs
Monitor your e-commerce checkout flow with Playwright synthetic tests. Learn to detect payment failures, cart issues, and conversion-blocking bugs before customers do.