Webhook Security

Secure your webhook integrations and protect against unauthorized requests.

Overview

Runframe webhooks use unique URLs to authenticate requests. Each webhook has a unique ID that acts as a shared secret between your system and Runframe.

Webhook URLs

URL format

https://api.runframe.io/webhooks/custom/{WEBHOOK_ID}

The WEBHOOK_ID is a cryptographically secure random string that:

• Uniquely identifies your webhook
• Acts as an authentication token
• Cannot be guessed or brute-forced

Getting your webhook URL

1. Navigate to Settings → Webhooks
2. Click New Webhook
3. Runframe generates a unique webhook URL
4. Copy the URL – it won’t be shown again in full

Best practices

1. Store securely

Do:

• Store in environment variables
• Use secret management tools (AWS Secrets Manager, HashiCorp Vault)
• Encrypt in configuration files
• Restrict file permissions (chmod 600)

Don’t:

• Don’t commit to git
• Don’t hardcode in scripts
• Don’t share in chat or email
• Don’t include in client-side code

Example: Environment variable

# .env file
RUNFRAME_WEBHOOK_URL=https://api.runframe.io/webhooks/custom/wh_abc123...

import os
webhook_url = os.environ['RUNFRAME_WEBHOOK_URL']

2. Use HTTPS only

Webhook URLs only work over HTTPS. Plain HTTP requests are rejected.

3. Rotate periodically

Regularly regenerate webhook URLs:

1. Navigate to Settings → Webhooks
2. Click Regenerate URL on your webhook
3. Update your tools with the new URL
4. Test the new URL
5. Old URL is immediately invalidated

Recommended rotation:

• Every 90 days for production integrations
• After any suspected exposure
• When team members with access leave

4. Monitor usage

Regularly review webhook delivery logs:

1. Navigate to Settings → Webhooks
2. Click on your webhook
3. View delivery history and error logs

Look for:

• Unexpected spikes in requests
• Failed deliveries
• Requests from unknown IPs

IP whitelisting

Restrict webhook requests to specific IP ranges.

Enabling IP whitelist

1. Navigate to Settings → Webhooks
2. Edit your webhook
3. Add allowed IP ranges in CIDR notation:
   • Single IP: 192.168.1.100
   • IP range: 192.168.1.0/24
   • Multiple ranges: 192.168.1.0/24, 10.0.0.0/16
4. Save changes

Common use cases

Testing security

Verify IP restrictions

Test from an allowed IP:

curl https://api.runframe.io/webhooks/custom/wh_abc123... \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"title": "Test from allowed IP"}'

Test from a disallowed IP (should fail):

# From a different IP
curl https://api.runframe.io/webhooks/custom/wh_abc123... \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"title": "Test from blocked IP"}'

Verify URL uniqueness

Each webhook URL is unique. Test that one webhook’s URL doesn’t work for another:

# Use Webhook A's URL
curl https://api.runframe.io/webhooks/custom/wh_abc123... \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"title": "Test"}'
 
# Try using Webhook B's URL with same payload
curl https://api.runframe.io/webhooks/custom/wh_def456... \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"title": "Test"}'

Both should succeed, creating separate incidents.

Revoking webhooks

Immediate revocation

If a webhook URL is exposed:

1. Navigate to Settings → Webhooks
2. Click Revoke on the compromised webhook
3. Confirm revocation
4. The webhook URL is immediately invalidated

All requests to the revoked URL will fail with:

{
  "success": false,
  "error": {
    "code": "WEBHOOK_REVOKED",
    "message": "Webhook has been revoked"
  }
}

After revocation

1. Create a new webhook with a fresh URL
2. Update your monitoring tools with the new URL
3. Test the new integration
4. Monitor for continued suspicious activity

Audit logging

Runframe logs all webhook deliveries for security auditing:

View logs in Settings → Webhooks → View Logs.

Need more?

• Webhooks – Creating and configuring webhooks
• Integrations – Pre-built Datadog, Sentry, and Prometheus guides
• Web Dashboard – Webhook management UI