Authentic and Idempotent Persona Event Intake
Overview
A webhook is an untrusted delivery until its signature passes. Persona may deliver duplicates or events out of order, so authenticity, durable receipt, idempotency, event-time ordering, and resource reconciliation are distinct steps.
Prerequisites
- HTTPS endpoint retaining exact raw request bytes
- Persona webhook secret with rotation metadata
- Durable unique event store and reconciliation worker
Instructions
Step 1: Capture before parsing
Read the exact raw bytes and Persona-Signature header. Enforce size, method, content-type, and timestamp policy before business work.
Step 2: Parse signature candidates
Extract t and every v1 value. Reject malformed or missing components; retain only redacted diagnostic metadata.
Step 3: Compute and compare
Compute HMAC-SHA256 with the webhook secret over t + '.' + rawBody. Compare against every v1 candidate in constant time to support rotation.
Step 4: Acknowledge durable receipt
After authenticity, insert the event ID and raw-body hash under a uniqueness constraint, then acknowledge quickly. Duplicate inserts are successful no-ops.
Step 5: Process in provider time
Route by event type while tolerating unknown types. Use data.attributes.created-at, not arrival order, to guard state transitions.
Step 6: Reconcile before consequential action
For approval, rejection, payout, or access changes, read the current Persona resource and apply the versioned domain policy.
Authentication
Webhook authentication uses the endpoint signing secret and the Persona-Signature HMAC protocol; it does not use the REST bearer key. Resource reconciliation uses the environment bearer key separately.
Tool Discipline
Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.
Output
- Signature-verification contract and test vectors
- Durable event receipt, dedupe, ordering, and routing design
- Reconciliation and business-transition receipt
Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer keys, webhook secrets, inquiry session tokens, raw identity documents, or unnecessary PII.
Examples
During rotation a header contains two v1 candidates. The consumer computes both constant-time comparisons, accepts the matching active secret, stores the event once, and ignores a later duplicate delivery.
Error Handling
| Failure | Response |
|---|---|
| Signature mismatch | Return the configured failure response, record a redacted hash and timestamp, and never enqueue business work. |
| Duplicate event | Acknowledge the already persisted ID without repeating side effects. |
| Older event arrives later | Store it for audit, compare provider creation time and current resource state, and prevent regression. |
| Unknown event type | Preserve and observe it safely; do not crash the intake lane. |
Validation
Verify the result against the linked first-party evidence, the pinned API version, redacted contract fixtures, an expected failure path, and the documented rollback or manual-disposition path. A successful request is not proof of a successful identity decision.