REFERENCE

Webhooks

Fidacy pushes signed events as your agents transact. Register an endpoint, verify the signature, and react — every delivery is signed with a verifiable key, retried with backoff, and idempotent by event id.

Register an endpoint

POST/v1/webhook-endpoints
curl https://api.fidacy.com/v1/webhook-endpoints \
  -H "Authorization: Bearer $FIDACY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/hooks/fidacy",
    "event_types": ["assessment.denied","agent.trust_changed"]
  }'

An empty event_types subscribes to everything. List your endpoints with GET /v1/webhook-endpoints and inspect deliveries for debugging.

Event types

assessment.completed

Any assessment finishes.

assessment.denied

A decision is deny.

assessment.flagged

A decision is review.

assessment.refined

The async reasoning layer changed a verdict.

agent.trust_changed

An agent’s trust tier moved.

Payload

{
  "id": "asmt_…:assessment.denied",
  "type": "assessment.denied",
  "created": "2026-06-19T01:12:04.991Z",
  "livemode": true,
  "data": {
    "assessment_id": "asmt_…",
    "decision": "deny",
    "risk_level": "highest",
    "risk_score": 88,
    "agent_id": "agt_…",
    "kind": "ap2_payment"
  }
}

Verify the signature

Every request carries a signature header and the key id that signed it. Fetch the public key by kid from the JWKS, verify the JWS over the raw body, and only then trust the event.

x-fidacy-signature

Compact JWS (EdDSA) over the delivery payload.

x-fidacy-key-id

The signing key id — look it up in /.well-known/jwks.json.

x-fidacy-token

Optional shared token if you set one on the endpoint.

Always verify the signature before acting on a webhook, and treat the endpoint as public-facing. Reject anything whose signature does not verify against a current Fidacy key.

Delivery semantics

At-least-once

A delivery is retried with backoff on any non-2xx or network failure until it succeeds or is exhausted.

Idempotent

Each delivery has a stable id ({assessment}:{type}) — dedupe on it so retries are safe.

Decoupled

Delivery runs off the assessment’s hot path; a slow or failing endpoint never affects a verdict.

← PREVIOUS
API Reference NEXT →
Security