On this page
Delivery and processing are different problems
A delivery can fail, repeat or arrive late. The contract includes delivery states such as retry_pending and failed; do not assume a fixed retry interval or exactly-once delivery. Confirm operational settings for your integration.
- Verify the signature and envelope before trusting an event.
- Persist acceptance with a unique
event_id, preventing races between receivers. - Make business continuation idempotent.
- Read the transaction with GET to reconcile current state.
If your receiver acknowledges before persistence and then crashes, work can be lost. If it persists and the acknowledgment is lost, delivery can repeat. Your design must handle both cases.
Arrival order is not authoritative state
A delayed created event must not overwrite a final state already known to your application. The transaction identifier locates the journey; event_id identifies each event. Call GET /v1/face-auth/transactions/{transaction_id} using the correct Tenant and environment key.
Prepare operational recovery
Record the identifier, event type, processing result and sanitized failure. Do not copy personal-data payloads or credentials into open logs. Define how your team finds pending work, performs a fresh read and avoids repeating releases, charges or other effects.
Test duplicate events, two events out of order, a failure before persistence and one afterward. The simulator explains scenarios; your queue and storage infrastructure still require their own tests.