A webhook lets Trust Gateway notify your application after it verifies a payment. It is useful for updating an invoice, unlocking a digital product, or queuing fulfilment without asking a person to refresh the dashboard. The receiving endpoint still has to authenticate the event and match it with an order in your own database.
- Create an order on your server and store its gateway order ID and payable amount.
- Save a public HTTPS endpoint in the dashboard's Webhooks section.
- Verify the signature and compare the notification with your stored order.
- Fulfil once; use the authenticated status API if a callback is missed.
1. Prepare a callback endpoint
Create a POST endpoint on your server, such as https://yourdomain.example/payments/trust-gateway. It must be reachable over HTTPS from the internet. Trust Gateway rejects private or local-only hosts and does not use browser code as a webhook receiver. Keep the endpoint's response fast: perform validation and durable recording first, then let a background worker handle slower delivery work in your application.
In your Trust Gateway dashboard, open Webhooks in the left navigation, enter the endpoint URL, and choose Save endpoint. The “Configured” badge confirms the URL was saved, not that a callback has been delivered. The dashboard does not currently provide a delivery log or test-send button. Confirm the flow with a real, low-value test payment.
2. Understand the payment event
After an order is verified as successful, the gateway sends a JSON POST with event payment.success. Useful fields include order_id, amount, requested_amount, status, gateway, and transaction references when available. FamPay checkouts may use a small payable-amount adjustment to distinguish concurrent orders; compare the returned payable amount with the amount stored for that gateway order rather than assuming it always equals the price you originally requested.
The signature is sent in the X-Gateway-Signature header. Its signing input is the order ID, amount formatted to two decimals, status, and UTR or NONE, joined with |. It is an HMAC-SHA256 hex digest. Follow the current webhook reference for the exact field contract. Do not assume that signing the raw JSON body produces the same digest.
3. Verify before changing an order
Recompute the documented HMAC with your configured webhook secret, or the merchant API key used as fallback, and compare the received and expected bytes in constant time. Reject a missing or mismatched signature. Then load the order from your own database, require the expected gateway order ID and amount, and check that its state transition is valid. Do not let a callback create a paid order with a reference your server never issued.
Keep secrets on the server. Never place the API key or webhook secret in a browser bundle, public URL, screenshot, or customer-facing page. For a complete verification example, use the code in Trust Gateway's API documentation.
4. Fulfil exactly once
More than one process in your application may encounter the same order update. Use a unique fulfilment record or an atomic state change so two handlers cannot ship twice. Record the gateway order ID and transaction reference alongside your internal order. If the event is already processed, return a successful response without repeating the business action.
A callback is a notification, not the only way to learn an order's state. Delivery can fail or be delayed, and retries are not guaranteed. If no webhook arrives, use the authenticated order-status endpoint from your server. Also test a pending payment, an expired checkout, a repeated event, and a request with a bad signature before making automatic fulfilment live.
Troubleshooting checklist
- No callback: confirm the endpoint is saved, publicly reachable over HTTPS, and that a real order reached verified success.
- Signature mismatch: confirm the exact signing fields, two-decimal amount, UTR-or-NONE value, and correct secret.
- Amount mismatch: compare with the gateway's payable amount returned when the order was created.
- Duplicate fulfilment: make the order update atomic and idempotent in your database.
Payment webhook questions
Where do I add my webhook URL?
Sign in to the Trust Gateway dashboard, choose Webhooks in the merchant navigation, enter a public HTTPS endpoint, and save. Confirm it with a real test payment because saving a URL does not test delivery.
Is a webhook enough to mark an order paid?
Only after your server verifies its signature and matches the order ID and payable amount with your own record. Keep an authenticated status lookup as a recovery path when the notification is late or absent.
What if the same payment notification arrives twice?
Make the fulfilment transition idempotent. A second valid notification for an already fulfilled order should be acknowledged without shipping, crediting, or granting access again.
Start with the first API order checklist if you have not yet created an order from your backend. A webhook is most useful once that order mapping already exists.