Receive webhooks

The gateway sends payment and refund events to the application's result URL. Each event includes id, type, payment_id, reference, sequence, environment, status, amount_minor, currency, receipt, occurred_at and a nullable refund object.

Verify the request

X-Xash-Event-Id: EVENT_UUID
X-Xash-Timestamp: UNIX_SECONDS
X-Xash-Signature: HEX_SIGNATURE

Calculate the expected signature using the exact raw request body:

$expected = hash_hmac('sha256', $timestamp.'.'.$rawBody, $signingSecret);
$valid = hash_equals($expected, $signature);

Reject an invalid signature or a timestamp more than five minutes from the current time. Match the event header to the body ID and check the expected environment.

Apply and acknowledge

Read the current payment from the API before applying a financial result. Store the event ID and wallet adjustment in the same database transaction. Enforce uniqueness so a repeated event cannot duplicate a credit or refund.

After committing, return HTTP 200 with:

{"acknowledged_event_id":"RECEIVED_EVENT_ID"}

The gateway requires the matching event ID. It retries unacknowledged deliveries up to 12 times, with delays capped at one hour. Administrators can replay a delivery from Operations after fixing the receiving endpoint.

Events can arrive late or out of order. Use the current API result and the unique payment or refund ID when applying money movements.