PlatformObserve

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"}}
HMAC-SHA256(secret, t + "." + body)Valid

Retried on failure · dead-letter queue · manual retry

Illustration of a signed webhook delivery
Event catalogue

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

Verify

Check every signature

python
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}
Delivery

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.

Every 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.