Webhooks — Event-Driven Extensibility

Webhooks let you react to events in FerrisKey by pushing HTTP notifications to external systems. When something happens — a user is created, a role is assigned, a client secret is rotated — FerrisKey sends an HTTP POST to your registered endpoints with a structured payload.

Why Webhooks?

FerrisKey manages identity, but your application lives outside of it. Webhooks bridge the gap:

Real-time sync — Keep external systems (CRM, data warehouse, email marketing) in sync with user changes without polling
Automation — Trigger downstream workflows when specific events occur (welcome emails, Slack notifications, provisioning)
Monitoring — Forward events to alerting systems for security-sensitive actions
Decoupling — Your application reacts to events without being tightly coupled to FerrisKey’s internals

How It Works

graph LR
    FK[FerrisKey] -->|Event occurs| Q[Event Queue]
    Q --> W1[Webhook: Slack]
    Q --> W2[Webhook: CRM Sync]
    Q --> W3[Webhook: SIEM]

Register a webhook

Create a webhook with a target endpoint URL, optional custom headers, and a name/description. The webhook is scoped to a realm.

Subscribe to events

Add subscribers to the webhook — each subscriber listens for a specific trigger event (e.g., user.created, client.deleted).

Events fire

When a matching event occurs in the realm, FerrisKey builds a payload and sends an HTTP POST to the webhook endpoint.

Webhook Structure

A webhook in FerrisKey consists of:

Field	Description
`id`	Unique webhook identifier
`endpoint`	Target URL for HTTP POST delivery
`headers`	Custom HTTP headers (e.g., `Authorization`, `X-Webhook-Secret`)
`name`	Human-readable name
`description`	Optional description
`subscribers`	List of event subscriptions
`triggered_at`	Last time any subscriber fired
`created_at` / `updated_at`	Timestamps

Real-World Patterns

User Onboarding

On user.created, send a welcome email, provision a trial account in your billing system, and notify the sales team in Slack.

Security Monitoring

Forward auth.reset_password and client.secret_rotated events to PagerDuty or Opsgenie for on-call alerting.

Data Sync

On user.updated and user.deleted, sync changes to your CRM, data warehouse, or marketing platform in real time.

Audit Forwarding

Forward all events to Splunk, Elastic, or a custom SIEM for long-term storage and compliance reporting.