Webhooks and Delivery
The exact events Identity sends, how deliveries are signed and retried, and the API for managing your webhook endpoints.
Why webhooks matter
Most customer platforms should not wait for a user to finish onboarding and then poll for the answer. Webhooks let Identity push meaningful state changes back into the customer system in near real time.
Verification lifecycle events
These are the event types Identity actually sends. Event names are permanent once published, and each payload carries a schema_version so you can evolve your handling over time without breaking on new fields.
What each one tells you
- identity.verification.created: a new KYC or KYB case was opened for a subject
- identity.check.completed: one check inside a verification finished, such as a single BVN lookup
- identity.verification.completed: the case reached a final decision, allow, review, or reject, with a risk score and level
- identity.verification.failed: the case could not complete, or was routed to manual review, with a retryable flag
- identity.risk.updated: the subject’s computed risk score or level changed
- identity.evidence.created: a new evidence artifact was registered and hashed
- identity.artifact.scan.completed and identity.artifact.quarantined: the security scan on an uploaded artifact finished, or the artifact was quarantined
- identity.document.analysis.completed: document forensics and OCR analysis on an uploaded ID finished
Event payloads never expose which verification source ran a check, and never carry raw document images or biometric data. Sensitive fields are references or digests you can look up through the API, not the underlying data itself.
Delivery, signing, and retries
Every delivery is signed so you can verify it actually came from Identity before you trust it.
What to expect
- each request carries an x-remllo-signature header: an HMAC-SHA256 signature of the raw JSON body, using your endpoint’s signing secret
- x-remllo-event-id and x-remllo-event-type headers identify the event without parsing the body first
- a failed delivery is retried up to 5 times, roughly 5, 10, 15, and 20 minutes apart, before it is marked exhausted
- retries reuse the same event id, so your handler should treat repeat deliveries of the same event id as a no-op
Recompute the HMAC-SHA256 signature over the exact raw request body using your endpoint secret, and compare it to the x-remllo-signature header before acting on a delivery.
Managing your endpoints
Webhook endpoints are managed through the same API you use for everything else, or from the console.