Webhooks and events
Signed events for every decision that matters.
Humane posts events to your endpoints as things happen: safety flags, holds and blocks, proactive triggers, takeovers, anomalies and more. Every delivery is signed with HMAC-SHA256, retried on failure and parked in a dead-letter queue if it keeps failing.
Webhook delivery
POST /hooks/humane
X-Humane-Event: safety.flagged
X-Humane-Delivery-Attempt: 1
X-Humane-Signature: t=1762000000,v1=5f2c…9ab1
{"event":"safety.flagged",
"data":{"user_id":"user_88","risk_level":"critical",
"flags":["self_harm"],"source":"observe"}}Retried on failure · dead-letter queue · manual retry
Subscribe to what you need
Pick events by name, use the proactive.* family, or subscribe to * for everything.
Safety
safety.flagged, safety.hold, safety.blocked
Proactive
proactive.triggered, proactive.mood_drop, energy_low, user_inactive, engagement_drop, trust_milestone, task_reminder, task_escalation, and your policy events
Takeover
takeover.started, takeover.message, takeover.released, takeover.expired
Responses
response.ready and interaction.processed for every processed message
Monitoring
anomaly.detected, experiment.started, experiment.concluded, engine.config_changed
Account
user.created, end_user.deleted, api_key.created, api_key.revoked
Check every signature
import json, os
from fastapi import FastAPI, HTTPException, Request
from humane_ai import verify_webhook_signature
app = FastAPI()
SECRET = os.environ["HUMANE_WEBHOOK_SECRET"]
@app.post("/hooks/humane")
async def humane_hook(request: Request):
raw = await request.body()
sig = request.headers.get("X-Humane-Signature")
if not verify_webhook_signature(SECRET, raw, sig): # also rejects replays
raise HTTPException(401, "invalid signature")
event = json.loads(raw) # {"event": ..., "timestamp": ..., "data": {...}}
if event["event"] == "safety.flagged":
d = event["data"]
page_on_call(d["user_id"], d["risk_level"], d["flags"], d["source"])
return {"ok": True}How deliveries work
- Envelope: event, timestamp and data
- Headers: X-Humane-Event, X-Humane-Event-Id, X-Humane-Delivery-Attempt
- X-Humane-Signature: t=<unix>,v1=<hex>, HMAC-SHA256 over t, a dot and the raw body
- SDK verifiers reject signatures older than five minutes
- Failed deliveries retried, then held in a dead-letter queue for manual retry
- Event names validated when you subscribe, so typos fail early
Webhook questions
Something else? Ask us.
Works well with
Risk alerts
Elevated or critical risk fires a signed safety.flagged webhook from both observe() and process(), whether or not a gate also acted. Send it to your own endpoint, Slack or Discord, and on to a human takeover.
ExploreProactive triggers
Humane watches each user's state and fires an event when a threshold is crossed: mood dropping, energy running low, a user going quiet, trust passing a milestone. Each trigger has a cooldown and carries a suggested action, and your app decides how to reach out.
ExploreAudit trail
Humane records gate outcomes, safety flags, webhook deliveries, engine decisions and admin actions, each with its reason. When someone asks why the AI did something, you can show them.
ExploreEvery AI should know who it's talking to.
The safety and human-oversight layer for emotional AI: user state across sessions, risk alerts, safety gates and human takeover, with every decision explained.
