Webhooks and Events
Consume Ryvra events reliably with verification, ordering assumptions, retry handling, and replay safety.
#Purpose
Describes event consumption architecture, verification requirements, and delivery semantics for production use.
#Integration prerequisites
- Public endpoint with secure transport and signature verification.
- Event store that persists payload, signature metadata, and processing outcome.
- Dead-letter or replay workflow for failed processing attempts.
#Request and response patterns
- Inbound event includes event ID, type, timestamp, and data payload.
- Consumer must acknowledge accepted processing attempts promptly.
- Non-acknowledged events are retried according to delivery policy.
#Lifecycle and state model
- Receive event and validate signature and basic schema.
- Deduplicate using event ID and operation identity keys.
- Apply business-state transition and persist processing result.
- Acknowledge success or move failed event into controlled replay queue.
#Error and failure taxonomy
- Signature verification failure due to secret mismatch or tampering.
- Transient consumer outage causing repeated redelivery attempts.
- Out-of-order delivery where later state arrives before earlier transition.
#Retry and idempotency guidance
Consumers must be idempotent by event ID and operation key so replay and redelivery cannot create duplicate side effects.
#Observability and debugging entry points
- Event delivery success, retry count, and acknowledgment latency by event type.
- Dead-letter queue size and replay success ratio.
- Correlation between webhook lag and merchant-facing state delays.