Event
A record of a change to a payment, game session, KYC check, bonus, player profile or another object.
Documentation / Webhooks
Webhooks and event delivery
Set up reliable status and event delivery between systems: from message creation and signature verification to receipt acknowledgement, redelivery and error monitoring.
Events
statuses and changes
Signature
authenticity verification
Retries
redelivery
Monitoring
history and diagnostics
Event flow
From creation to acknowledgement
01
Create an event
Specify the identifier, type, time, object, status and related data.
02
Sign and send
Send the event over HTTPS with a signature and a limited timeout.
03
Acknowledge receipt
After verification, store the event and quickly return a successful HTTP response.
04
Retry on error
Retry delivery with increasing intervals and retain undelivered events for investigation.
Overview
A webhook reports a state change
The sender may retry delivery, so the recipient must verify the source, acknowledge receipt and apply each event only once.
Acknowledgement
The recipient returns a successful HTTP response after verifying and reliably storing the event.
Recovery
Redelivery and reconciliation help restore data after temporary unavailability of either system.
Event structure
What an event should contain
A consistent message structure simplifies verification, routing, duplicate protection and support for different event types.
Event identifier
A unique value used by the system to recognise redelivery and find the processing history.
Event type
A clear, stable name that defines the change that occurred and how it should be processed.
Creation time
The date and time the event was created, in the agreed format and time zone.
Related object
The type and identifier of the payment, player, round, request, bonus or another object.
Schema version
A version number helps safely change the message structure without disrupting active integrations.
Operation correlation
The identifier of the original request, transaction, session or chain of related actions.
Context
Brand, project, market, environment, provider and other data required for correct routing.
Event data
The minimum set of fields required to process the change or make a subsequent API request.
Signature and verification
Verifying event authenticity and integrity
Before changing data, the recipient verifies the secure connection, signature, creation time and unique event identifier.
01
Capture the raw message
Verify the signature against the raw request body before changing the JSON format.
02
Check the timestamp
Reject the request if the event time falls outside the permitted window.
03
Verify the signature
Use the agreed secret and HMAC or digital-signature algorithm.
04
Check the identifier
Confirm that the event has not already been applied and store the verification result.
Delivery and retries
HTTP responses and redelivery
The sender must distinguish between successful receipt, a temporary error and a permanent failure, while the recipient must respond quickly and unambiguously.
Successful HTTP response
Confirms that the event has been verified and reliably stored for further processing.
Limited timeout
Do not perform lengthy processing before responding to the sender — store the event first.
Redelivery
Retry delivery after a temporary network error, unavailability or no response.
Increasing retry interval
Gradually increase the delay between attempts to avoid creating additional load.
Undelivered event queue
After all attempts are exhausted, retain the event for diagnostics and manual handling.
Manual redelivery
An operator can resend a selected event without creating a new operation.
Delivery monitoring
Track the number of attempts, responses, the latest error and the next delivery time.
Alerts
Alert the team when errors increase, retries are exhausted or events accumulate in the queue.
Event processing
Duplicate protection and status ordering
The recipient must not rely on single delivery or strict event ordering.
Apply once only
Store the event identifier before changing data.
Acknowledge a repeated event without another debit, credit or state change.
Link the event to the object and its current state.
Store the event and business change as one consistent operation.
Ordering and freshness
Compare the timestamp, sequence number or event version.
Do not return an object to an outdated state when an older event arrives late.
Allow only valid transitions between statuses.
If there is any doubt, request the current object state through the API.
Testing
What to test before launch
Test successful delivery, invalid signatures, duplicates, slow responses, out-of-order events and recovery after a failure.
Invalid signature
Modified message, unknown key, expired timestamp and unsupported algorithm.
Redelivery
The same event arrives several times before and after processing is completed.
Slow response
The recipient takes too long to respond, the connection drops or the acknowledgement does not reach the sender.
Out-of-order processing
A final status arrives before an intermediate one, and an older event is delivered after a newer one.
Unavailable endpoint
Test HTTP 5xx errors, DNS, TLS, rate limits and complete exhaustion of retry attempts.
Delivery history
All attempts, responses, errors and manual redelivery results should be searchable by event identifier.
Pre-launch checklist
Production delivery is enabled after security, duplicate protection, redelivery and error monitoring have been verified.
Test and production environments use different endpoints and signing secrets.
The signature is verified against the raw message together with its creation time.
The event identifier is stored and protects operations from being executed more than once.
The recipient quickly returns a successful HTTP response after storing the event.
Retries, increasing intervals and manual redelivery are configured.
Delivery history and identifier-based search are available to the support team.
Need to set up reliable event delivery?
Provide the event list, receiving endpoints and status transition rules. APIACE will help define the message structure, signature verification, redelivery and error monitoring.