Reference

Webhooks

Fidacy queues signed event deliveries after the relevant product path completes. Register an endpoint, verify the compact JWS over the exact delivery body, and deduplicate using the delivery 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",
    "eventTypes": ["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

Event	Fires when
`assessment.completed`	Any assessment finishes.
`assessment.denied`	A decision is deny.
`assessment.flagged`	A decision is review.
`agent.trust_changed`	An agent's trust tier moved.
`agent.suspended`	An agent is suspended.
`agent.revoked`	An agent is revoked.
`audit.integrity_alert`	An audit-integrity alert is raised.
`key.rotation`	A signing-key rotation event is emitted.
`spend.review_required`	Spend Guard requires a human confirmation.
`spend.denied`	Spend Guard denied a spend.
`spend.confirmed`	A spend confirmation is recorded.

Payload

{
  "id": "dlv_…",
  "type": "assessment.denied",
  "created": 1781703124,
  "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.

Header	Value
`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.
·At least once, deduplicate at the receiver. Each delivery has its own stable id. Persist it before processing so a retry does not repeat your side effect.
·Decoupled.Delivery runs off the assessment's hot path; a slow or failing endpoint never affects a verdict.

← PreviousAPI Reference

Next →Security