Custom Webhooks

BlameTrail can send real-time HTTP notifications to your own endpoints when incidents and deploys occur. Custom webhooks let you integrate BlameTrail with internal tools, ticketing systems, chat platforms, or any service that accepts HTTP requests.

Creating a webhook endpoint

Via the UI

1. Navigate to Organization > Integrations > Webhooks.
2. Click Add Endpoint.
3. Enter:
   • URL — The HTTPS endpoint that will receive webhook deliveries.
   • Name — A human-readable label (e.g., PagerDuty Bridge, Internal Dashboard).
4. Click Save.

BlameTrail generates a signing secret for the endpoint. Copy and store it securely -- you will need it to verify incoming webhook signatures.

Via the API

curl -X POST "https://blametrail.com/api/webhooks/endpoints" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-token" \
  -d '{
    "url": "https://your-server.com/blametrail-webhook",
    "name": "Internal Dashboard"
  }'

The response includes the endpoint ID and signing secret.

Event types

BlameTrail sends the following event types:

See Event Types for complete payload documentation.

Security

All webhook deliveries are signed with HMAC-SHA256 using the endpoint's signing secret. Each request includes:

• X-BlameTrail-Signature — The HMAC-SHA256 signature
• X-BlameTrail-Timestamp — Unix epoch timestamp of the delivery
• X-BlameTrail-Event — The event type
• X-BlameTrail-Delivery — A unique delivery ID

Your endpoint should verify the signature before processing the payload. See Signature Verification for implementation details and code examples.

Delivery guarantees

BlameTrail retries failed deliveries up to 5 times with exponential backoff. Endpoints that fail 10 consecutive deliveries are automatically disabled. See Delivery Behavior for the full retry schedule and troubleshooting guidance.

Managing endpoints

Testing an endpoint

Click Send Test next to an endpoint to send a test.ping event. This verifies that your endpoint is reachable and processing signatures correctly.

Disabling an endpoint

Toggle the endpoint to inactive to pause deliveries without deleting the configuration. Re-enable at any time to resume.

Deleting an endpoint

Delete an endpoint to permanently remove it and stop all deliveries. This action cannot be undone.

Next steps

• Event Types — Detailed payload documentation for each event type
• Signature Verification — Code examples for verifying HMAC signatures
• Delivery Behavior — Retry schedule, timeouts, and troubleshooting