Webhooks
Configure webhook endpoints to receive real-time event notifications from the gateway.
About
Prism can send real-time HTTP notifications to your endpoints when gateway events occur, such as completed requests, triggered guardrails, exceeded budgets, and errors. Use webhooks to build integrations, trigger alerts, or log events in your own systems.
When to use
- Alerting: Get notified immediately when error rates spike or budgets are exceeded
- Audit logging: Stream every request event to your own data pipeline
- Guardrail monitoring: React when a guardrail triggers on a request
- Cost control: Trigger actions when a budget threshold is hit
Setting up a webhook
- Go to Gateway > Webhooks
- Click + Create Webhook
- Fill in the form:
| Field | Required | Description |
|---|---|---|
| Name | Yes | A label for this endpoint |
| URL | Yes | Your HTTPS endpoint, e.g., https://example.com/webhook |
| Secret | Optional | HMAC secret for verifying payload signatures |
| Description | Optional | Notes about this webhook |
| Event Subscriptions | Optional | Select which events to receive (see below) |
- Click Create
Event types
| Event | Trigger |
|---|---|
request.completed | A gateway request finishes (success or error) |
guardrail.triggered | A guardrail rule fires on a request |
budget.exceeded | Spend crosses a configured budget limit |
error.occurred | A gateway-level error occurs |
batch.completed | A batch processing job finishes |
Subscribe to only the events you need to reduce noise.
Payload verification
If you set a Secret, Prism signs each request with HMAC-SHA256 and includes the signature in the X-Prism-Signature header. Verify it on your server to confirm the payload came from Prism.
import hmac
import hashlib
from fastapi import FastAPI, Request, HTTPException
app = FastAPI()
WEBHOOK_SECRET = "your-webhook-secret"
@app.post("/webhook")
async def handle_webhook(request: Request):
payload = await request.body()
signature = request.headers.get("X-Prism-Signature", "")
expected = hmac.new(
WEBHOOK_SECRET.encode(),
payload,
hashlib.sha256,
).hexdigest()
if not hmac.compare_digest(f"sha256={expected}", signature):
raise HTTPException(status_code=401, detail="Invalid signature")
data = await request.json()
event_type = data.get("event")
# Handle the event
print(f"Received event: {event_type}")
return {"status": "ok"}import hmac
import hashlib
from flask import Flask, request, abort, jsonify
app = Flask(__name__)
WEBHOOK_SECRET = "your-webhook-secret"
@app.route("/webhook", methods=["POST"])
def handle_webhook():
payload = request.get_data()
signature = request.headers.get("X-Prism-Signature", "")
expected = hmac.new(
WEBHOOK_SECRET.encode(),
payload,
hashlib.sha256,
).hexdigest()
if not hmac.compare_digest(f"sha256={expected}", signature):
abort(401)
data = request.get_json()
event_type = data.get("event")
# Handle the event
print(f"Received event: {event_type}")
return jsonify(status="ok")Delivery log
The Delivery Log tab on the Webhooks page shows the status of every webhook delivery attempt, including timestamp, HTTP status code, and response body. Use it to debug failed deliveries and retry them manually.