A payment webhook is a notification, not a licence to trust the public internet blindly. Networks retry requests, servers restart, and a customer can return before a callback arrives. A reliable Trust Gateway integration validates every event, stores enough context to process it safely, and falls back to authenticated order status when notification delivery is uncertain.
- Receive the HTTPS request.
- Validate the documented signature.
- Find the saved local order.
- Compare order ID and exact amount.
- Fulfil once, then return success.
Validate before you parse a payment decision
Configure a public HTTPS endpoint that your server controls. Validate the Trust Gateway signature according to the documented signing contract and use a constant-time comparison. Reject missing or invalid signatures without changing a business order. Do not rely on an IP address, a browser origin or a JSON field supplied without verification as the only authenticity check.
Keep the webhook secret in server configuration, not in React code, a public repository or a support ticket. Rotating a secret should be a planned operational task: accept the documented transition behaviour, update the endpoint configuration, test a controlled event, and retire the old value. See the webhook documentation for setup details.
Assume the same event can arrive more than once
Retries are normal. Your handler should store a stable event or order reference and make the local paid-to-fulfilled transition atomic. If the order has already been fulfilled, return a safe successful response without granting another product, subscription day or account credit.
Idempotency belongs in your database transaction, not only in an in-memory process variable. A process restart can erase memory; a database uniqueness constraint or guarded status update can preserve the one-time rule. The local order is the source of which business action belongs to the gateway order.
Use authenticated status as the recovery path
A webhook can be delayed, blocked or missed. A background job, return page or support workflow can query the authenticated status endpoint for the same saved gateway order. Compare the response with the stored ID and payable amount, then apply the same idempotent fulfilment routine used by the webhook.
Do not create a replacement order just because a callback has not appeared quickly. Keep the original purchase pending while checking it. The webhooks and status API guide shows how both signals work together.
Return sensible endpoint responses
Return a successful response only after you have safely persisted the event outcome or verified that it was already processed. A temporary database outage should be visible to monitoring and may justify a retriable server error. Avoid long synchronous tasks such as email campaigns or slow file delivery in the request path; persist the verified payment first and let a separate worker handle follow-up work.
Log the event time, gateway order ID, local order ID, result and processing outcome. Do not log API keys, webhook secrets, full payer-sensitive data or credentials. These logs make delayed-payment support measurable without turning operational logs into a security liability.
Test retry and failure scenarios
- Deliver the same valid event twice and confirm one fulfilment.
- Send an invalid signature and confirm no order changes.
- Temporarily make the database unavailable and confirm the failure is observable.
- Mark an order through authenticated status first, then process the callback later.
- Refresh the buyer return page while a webhook is being processed.
These tests keep notification timing separate from the business outcome. Read the webhook idempotency guide and the security checklist before putting a callback into production.