Engineering · 2026-03-23

Designing an Identity Playbook Engine: From Signal to Action in One API Call

By J. W. Bouckaert

The problem with sequential identity

Most identity platforms process signals the way a call center handles tickets: one at a time, in sequence, with a human-readable queue. A carrier sends a SIM-swap alert. The platform logs it. A rules engine evaluates it. If it matches a policy, the platform dispatches an action—revoke a session, send an email, fire a webhook. Each step waits for the previous step to complete. Each step adds latency.

This architecture was adequate when identity verification was a batch process—something that happened during onboarding or password reset. It is inadequate when identity verification is a continuous, real-time operation that must respond to threats faster than an adversary can exploit them. The 50-millisecond budget is the operational requirement set by the gap between SIM-swap execution and fraudulent transaction initiation.

Event-driven identity orchestration replaces the sequential queue with a fan-out pipeline. A single ingest endpoint receives a signal, validates it, normalizes it, and dispatches it to multiple action handlers concurrently. The processing is faster, and the architecture is fundamentally different: it treats identity threat response as a distributed systems problem instead of a workflow automation problem.

Anatomy of the ingest endpoint

The PasskeyBridge ingest pipeline accepts carrier signals via a single POST endpoint. The request contains a JSON payload with a signal type, a phone hash, and carrier-specific metadata. The endpoint's responsibility is narrow: authenticate the request, validate the schema, normalize the signal, and hand it off to the orchestrator. It does not evaluate risk. It does not execute actions. It does not query external services.

This separation of concerns is critical. The ingest endpoint operates in the request-response hot path—every millisecond spent here is a millisecond added to the client's perceived latency. By constraining the endpoint to validation and dispatch, the pipeline maintains sub-10ms ingest latency regardless of the complexity of downstream actions.

Authentication and validation

Every inbound signal is authenticated via HMAC-SHA-256 signature verification. The carrier or integration partner signs the request body with a shared secret; the ingest endpoint recomputes the signature and rejects mismatches with a 401. This is not optional. Unsigned payloads are rejected regardless of content.

Schema validation uses Zod to enforce runtime type safety on the payload. The validator checks that the signal type is one of the seven canonical types (SIM swap, port-out, device change, account takeover, number recycling, call forwarding, and fraud score update), that the phone hash is a 64-character hexadecimal string, and that required metadata fields are present. Malformed payloads receive a 422 with a structured error response—never a generic 500.

Zero-PII normalization

The ingest endpoint enforces the platform's zero-PII architecture at the boundary. If a carrier sends a raw phone number (some legacy integrations still do), the endpoint hashes it to SHA-256 before any persistence or downstream processing occurs. The raw value never touches a database, a log, or an in-memory cache. That is an architectural constraint enforced at the code level rather than a policy decision, consistent with GDPR Art. 25 data protection by design.

The normalized signal—now a canonical type, a phone hash, and validated metadata—is passed to the orchestrator as a typed event object. From this point forward, no component in the pipeline has access to the original phone number. The hash is the identity.

The orchestrator: fan-out over waterfall

The orchestrator is the core of the playbook engine. It receives a normalized signal event and determines which actions to execute, in what order, and with what parameters. The design principle is fan-out: independent actions execute concurrently, dependent actions execute in sequence, and no action blocks the ingest response.

Playbook matching

When a signal arrives, the orchestrator queries the tenant's active playbooks for a match. Matching is deterministic: a playbook specifies a trigger type (signal match, threshold, or schedule) and a signal type filter. If the incoming signal's canonical type matches a playbook's filter, the playbook's action chain is dispatched for execution.

Multiple playbooks can match a single signal. A SIM-swap signal might trigger both a "SIM Swap—Critical Response" playbook (revoke sessions, freeze credentials) and a "SIM Swap—Compliance Notification" playbook (email the compliance team, log to the audit trail). Both execute concurrently.

Action chain execution

Each playbook defines an ordered list of actions. The current action vocabulary includes:

Actions within a playbook execute in configured order. This ordering matters: you revoke sessions before sending the webhook callback, ensuring that by the time your application receives the notification, the threat has already been neutralized. Detection without response is just logging.

Concurrency model

The orchestrator uses a fire-and-forget pattern for playbook execution relative to the ingest response. The ingest endpoint returns a 200 to the caller as soon as the signal is validated and the event is persisted to shield_events. Playbook execution happens asynchronously—the caller does not wait for actions to complete.

Within a playbook, actions execute sequentially (action 1 completes before action 2 begins). Across playbooks, execution is concurrent—Playbook A and Playbook B run in parallel. This model ensures that a slow webhook callback in Playbook B does not delay the session revocation in Playbook A.

Carrier lookup: The first signal enrichment

For signals that include a phone hash associated with a known carrier, the orchestrator can invoke carrier lookup as an enrichment step before playbook matching. Carrier lookup queries Vonage Number Insight, Twilio Lookup, or a configured custom provider to retrieve real-time carrier metadata: current carrier, porting status, roaming status, and fraud risk score.

This enrichment is optional—not every signal requires it, and not every tenant configures a carrier provider. When enabled, carrier lookup runs as a synchronous step between validation and playbook matching, typically completing in 15–35ms depending on the provider. The enriched metadata is merged into the signal event before playbook matching, allowing playbooks to trigger on enriched attributes (e.g., "trigger only if the carrier risk score exceeds 0.8").

Risk scoring: Deterministic and non-deterministic layers

The pipeline implements two risk-scoring layers, each with a distinct latency profile and trust model.

Deterministic scoring (in-line)

The deterministic layer applies rule-based scoring within the orchestrator's hot path. Rules evaluate signal attributes against configured thresholds: a SIM swap within 24 hours of a high-value transaction attempt might receive a risk score of 0.95; a routine device change with no recent transaction activity might receive 0.3. Deterministic scoring adds 1–3ms to the pipeline and produces a risk_score field on the event record.

Non-deterministic scoring (shadow execution)

The intelligence layer runs asynchronously via shadow execution—a fire-and-forget invocation of the shield-intelligence-worker that has zero impact on the critical path. This layer uses behavioral clustering (Jaccard similarity) and LLM-assisted analysis to identify coordinated attack patterns, generate SHAP-style explainability reports, and flag signals for human-in-the-loop review.

Shadow execution means the intelligence layer can take 500ms, 2 seconds, or 10 seconds without affecting the ingest response or playbook execution. High-risk intelligence findings retroactively trigger Level 2 playbooks—escalation actions that run after the initial response has already neutralized the immediate threat.

VC issuance: Closing the loop with verifiable credentials

After threat neutralization, the pipeline can issue a W3C Verifiable Credential that attests to the identity verification outcome. This is the Pillar II integration point: a signal that was ingested via Pillar I (carrier signals) and validated via Pillar III (WebAuthn biometric binding) produces a cryptographically signed credential that the user or relying party can present in future interactions.

The VC issuance action uses the platform's self-hosted VC engine—a JWT-only system with native did:web and did:key resolution, hybrid ML-DSA-65 post-quantum signatures (NIST FIPS 204), and automatic cross-reference binding. Issuance completes in under 10ms for local operations, making it viable as a playbook action inside that budget.

The issued credential is stored in the tenant's credential registry and optionally pushed to the user's VC wallet via the PasskeyBridge SDK. This creates a closed loop: signal → response → attestation → future verification. The credential is proof that the identity survived a threat challenge—a primitive that traditional auth systems cannot produce.

Webhook delivery: Reliability at the edge

Outbound webhook delivery is the most latency-variable component in the pipeline. The tenant's endpoint might respond in 5ms or 500ms. It might be down. It might rate-limit. The playbook engine handles this with a standardized retry mechanism: 4 attempts with exponential backoff (1s, 2s, 4s, 8s maximum). Each delivery attempt is logged to shield_webhook_deliveries with the request body, response status, response body (truncated to 2KB), attempt count, latency, and error message.

The webhook payload includes the signal type, phone hash, tenant ID, timestamp, and the full event metadata—everything the tenant needs to take application-level action without querying the PasskeyBridge API. For tenants that require payload integrity verification, the platform signs the webhook body with HMAC-SHA-256 using the tenant's signing secret and includes the signature in the x-pb-signature header. This allows the receiving application to verify that the payload was not tampered with in transit.

Audit trail: Append-only, zero-PII

Every action in the pipeline writes to the immutable audit trail. The audit record includes the actor (system, user hash, or API key hash), the action type, the resource type and ID, the result (success or failure), and a metadata object with action-specific details. It does not include PII—consistent with the platform's zero-PII architecture.

The audit trail serves three purposes: operational debugging (why did this playbook not fire?), compliance evidence (SOC 2, Reg S-ID), and forensic analysis (what happened in the moments after the SIM swap?). Every record is timestamped, tenant-scoped, and queryable via the dashboard's Audit Log viewer.

A single API call, end to end

Here is what happens when a carrier sends a SIM-swap signal to the PasskeyBridge ingest endpoint:

1. T+0ms: HMAC-SHA-256 signature verified. Payload validated against Zod schema.
2. T+2ms: Phone number (if raw) keyed-hashed with HMAC-SHA-256 under a server-held pepper. Signal normalized to canonical sim_swap type.
3. T+4ms: Event persisted to shield_events. Usage counter incremented. 200 returned to caller.
4. T+5ms: Orchestrator matches two active playbooks. Execution begins concurrently.
5. T+7ms: Playbook A: Sessions revoked. Passkey credentials frozen. Agent delegates suspended.
6. T+12ms: Playbook A: Webhook callback dispatched to tenant's incident handler.
7. T+8ms: Playbook B: Compliance email dispatched via Resend. Audit log entry written.
8. T+15ms: Intelligence worker invoked asynchronously (shadow execution). No critical-path impact.
9. T+22ms: Webhook delivery confirmed. Delivery log persisted with response metadata.
10. T+35ms: VC issued attesting to identity verification outcome. Cross-reference binding updated.

Total critical-path latency (caller perspective): 4ms. Total orchestration latency (all actions complete): ~35ms. That leaves margin inside the orchestration envelope for carrier API variance and network jitter.

Detection with response

The identity industry is converging on a recognition that detection without automated response is a liability, not a capability. Gartner's Identity Threat Detection and Response (ITDR) category is evolving toward what PasskeyBridge defines as Identity Threat Response as a Service (ITRaaS)—platforms that neutralize threats rather than only detecting them within the window of exploitation.

The playbook engine is the mechanism that makes ITRaaS operational. It transforms a single carrier signal into a coordinated, multi-system response that spans session management, credential lifecycle, agent governance, webhook notification, credential issuance, and audit logging—all within a single API call.

This is distributed systems engineering applied to identity rather than workflow automation dressed up as security. The signals are real-time. The actions are atomic. The architecture is event-driven. And the entire pipeline operates with zero PII stored, post-quantum signatures on every credential, and an append-only audit trail that satisfies SOC 2 and SEC Reg S-ID without ever recording a phone number.

Explore the API →

Start free · Test the API