Webhook Security

Secure your webhook integrations and protect against unauthorized requests.

Overview

Runframe uses two layers of security for incoming webhooks:

1. Routing key — A secret URL that authenticates and routes requests (always required)
2. Signature verification — HMAC-SHA256 or provider-specific signatures (varies by integration)

Routing keys

URL format

https://api.runframe.io/webhooks/{routingKey}

The routingKey is a cryptographically secure random string that:

• Uniquely identifies your integration
• Routes webhooks to the correct organization and service
• Acts as an authentication token
• Cannot be guessed or brute-forced

Getting your webhook URL

1. Navigate to Integrations Hub in the Runframe dashboard
2. Click Connect for your integration (Datadog, Sentry, Prometheus, CloudWatch, or Custom Webhook)
3. Runframe generates a unique webhook URL
4. Copy the URL and configure it in your monitoring tool

Signature verification

Different integrations use different verification methods:

Custom Webhook HMAC signing

When a signing secret is configured for your Custom Webhook integration, Runframe requires two headers:

X-Runframe-Signature: sha256=<hex HMAC of timestamp.body>
X-Runframe-Timestamp: <unix seconds>

The signature is: HMAC-SHA256(signingSecret, "${timestamp}.${body}")

Replay protection: Runframe uses an asymmetric replay window — timestamps older than 5 minutes in the past or more than 1 minute in the future are rejected.

See the Webhooks reference for signing examples in multiple languages.

CloudWatch SNS verification

CloudWatch webhooks arrive via SNS. Runframe automatically:

• Validates the signing certificate URL (must be sns.*.amazonaws.com)
• Caches certificates for 24 hours
• Verifies RSA signatures (SignatureVersion 1 and 2)
• Auto-confirms SNS subscriptions

No configuration needed — SNS verification is always on.

Rate limiting

Runframe rate-limits incoming webhooks to 100 requests per minute per routing key. Requests exceeding the limit receive a 429 Too Many Requests response.

Best practices

1. Store URLs securely

Do:

• Store in environment variables
• Use secret management tools (AWS Secrets Manager, HashiCorp Vault)
• 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/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 after exposure

If a webhook URL is accidentally exposed:

1. Navigate to Integrations Hub
2. Disconnect the affected integration
3. Reconnect to generate a fresh routing key
4. Update your monitoring tools with the new URL
5. The old URL is immediately invalidated

4. Enable HMAC signing for Custom Webhooks

For Custom Webhooks, configure a signing secret for an additional security layer beyond the routing key. This is especially important when the webhook URL might be visible in CI/CD logs or shared configurations.

5. Review webhook event logs

Runframe logs all incoming webhook events in the webhook_event_logs table. Review logs periodically for:

• Unexpected spikes in requests
• Failed signature verifications
• Requests with invalid payloads

Need more?

• Webhooks — Webhook endpoint, payload format, and signing examples
• Integrations — Setup guides for Datadog, Sentry, Prometheus, CloudWatch, and Custom Webhook
• Web Dashboard — Integration management UI