Webhooks send HTTP POST requests to your endpoints when specific events occur in Raven. Use them to trigger alerts, sync data to external systems, or build custom automation workflows.
Creating a Webhook
Navigate to Webhooks
Go to Webhooks in the dashboard sidebar.
Click Create Webhook
Enter the endpoint URL where you want to receive events.
Select Events
Choose which event types to subscribe to.
Copy the Secret
Save the webhook secret for signature verification. This is only shown once.
Event Types
Subscribe to any combination of events across the system.
Request Events
| Event | Description |
|---|
request.started | A request began processing |
request.completed | A request was successfully completed |
request.failed | A request failed |
request.cached | A request was served from cache |
request.fallback | A request used a fallback provider |
Guardrail Events
| Event | Description |
|---|
guardrail.triggered | A guardrail rule matched content |
guardrail.blocked | A request was blocked by a guardrail |
guardrail.warned | A guardrail issued a warning |
Budget Events
| Event | Description |
|---|
budget.threshold.reached | A budget reached its alert threshold |
budget.exceeded | A budget limit was exceeded |
budget.reset | A budget was reset for a new period |
Key Events
| Event | Description |
|---|
key.created | A virtual key was created |
key.revoked | A virtual key was revoked |
key.rate_limited | A key hit its rate limit |
key.expired | A virtual key expired |
Provider Events
| Event | Description |
|---|
provider.health.degraded | A provider’s health degraded |
provider.health.recovered | A provider recovered from degraded health |
provider.outage.detected | A provider outage was detected |
Webhook Payload
Each webhook delivers a JSON payload with the event details:
{
"webhookId": "wh_abc123",
"event": "budget.threshold.reached",
"timestamp": "2026-03-15T10:30:00Z",
"data": {
"budgetId": "bud_xyz789",
"budgetName": "Production API",
"currentSpend": 450.00,
"limit": 500.00,
"percentage": 90
}
}
Signature Verification
Every webhook request includes an X-Raven-Signature header containing an HMAC-SHA256 signature. Verify it to ensure the webhook came from Raven.
import crypto from "node:crypto";
function verifyWebhook(payload: string, signature: string, secret: string): boolean {
const expected = crypto
.createHmac("sha256", secret)
.update(payload)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
// In your webhook handler
app.post("/webhooks/raven", (req, res) => {
const signature = req.headers["x-raven-signature"];
const isValid = verifyWebhook(JSON.stringify(req.body), signature, WEBHOOK_SECRET);
if (!isValid) {
return res.status(401).send("Invalid signature");
}
// Process the event
console.log("Event:", req.body.event);
res.status(200).send("OK");
});
Always verify webhook signatures before processing events. Without verification, an attacker could send fake events to your endpoint.
Retry Logic
Failed webhook deliveries are retried with exponential backoff:
| Attempt | Delay |
|---|
| 1 | Immediate |
| 2 | 1 second |
| 3 | 2 seconds |
| 4 | 4 seconds |
Testing Webhooks
Use the dashboard to send test events to your webhook endpoint:
- Navigate to the webhook in the dashboard
- Click Send Test Event
- Select the event type to simulate
- Check your endpoint for the test payload
