> For the complete documentation index, see [llms.txt](https://docs.ecommerce.seb.ee/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ecommerce.seb.ee/integration/merchant-api/webhooks.md). # Webhooks Server-to-server notifications that tell your systems when a payment status or a gateway token changes – the reliable alternative to waiting for the customer’s browser. Whenever a payment changes status – it is paid, fails, is cancelled, expires, or is refunded – the gateway sends a **Webhook (also referred to as callback notifications)** to the configured Callback URL. Your systems can then update the order automatically, without anyone watching the Merchant Portal and without depending on the customer’s browser returning to your website. Webhooks are delivered server-to-server, independently of what the customer does. They arrive even if the customer closes the browser after paying, loses connection, or never returns to your shop. Fulfil orders based on the payment status confirmed through the gateway, not on the customer’s return. Webhooks are recommended for every integration type – Merchant API, Hosted Checkout, Web Plugins, and Payment Links. Web Plugins process Webhooks as part of their standard functionality. For your own integrations, implement a Webhook endpoint. ### How It Works 1. Configure your Callback URL. In the Merchant Portal, set the HTTPS endpoint on your side that will receive notifications for the shop. 2. A payment changes status. The customer pays, abandons the payment, a capture completes, a refund is processed – any status change triggers a notification. 3. The gateway notifies your endpoint. The notification tells you which payment changed (Payment ID) and its latest status. Your endpoint acknowledges receipt with a success response. 4. You retrieve the payment details. After receiving the notification, call the Get Payment Information API to retrieve the complete, current payment details – the notification is the trigger; the API response is the authoritative source. 5. You update your order. Based on the confirmed status, update the order: fulfil on the paid status, release inventory on a final failure, record the refund, and so on. See Payment Statuses for the recommended action per status. {% hint style="info" %} Treat the notification as a signal, not as the data. Always retrieve the payment details through the authenticated API before updating your order – this both gives you the full current state and protects you against forged or stale notifications. {% endhint %} {% hint style="warning" %} Do not poll Get Payment Information for every initiated payment. Use Webhooks as the normal trigger for status retrieval. Query the API only for exceptions, such as a notification not arriving within an expected period, or when an operator manually requests up to date payment details. {% endhint %} ### What Triggers a Notification * Payment status changes. Every change of the payment status – for card payments and Pay by Bank alike. This includes refund-driven changes: when a refund completes, the payment status changes to Refunded and a notification is sent. * Token changes. Where tokenization is enabled, the gateway notifies you about token changes – for example, when a stored token is suspended or deactivated – so you can keep saved payment methods up to date and pause merchant-initiated charges. See Tokenization. ### Designing your Webhook endpoint * Use HTTPS. Webhooks are delivered only to secure endpoints. Restrict the endpoint to Webhook processing. * Respond quickly. Acknowledge the notification immediately and process it asynchronously if possible. Long-running business logic inside the request handler leads to timeouts and unnecessary retries. * Be idempotent. The same notification may be delivered more than once – for example, after a retry. Processing a notification twice must not create duplicate fulfillments, duplicate refund records, or duplicate customer emails. * Fetch before acting. Never act from the notification payload alone – fetch the payment or gateway token via the API and act on the confirmed state. * Expect out-of-order and clustered events. Always act on the latest confirmed state from the API rather than assuming an order of arrival. * Keep an audit trail. Log received notifications with timestamps – they are invaluable for support cases and reconciliation. ### Delivery Retries and Missed Notifications If your endpoint is temporarily unavailable or does not acknowledge the notification, the gateway automatically retries delivery using an increasing retry schedule. If all retry attempts are exhausted, no further notifications are sent for that event. Design for the possibility of a missed notification: * Monitor your endpoint’s availability and error rates – a broken endpoint fails silently from the customer’s perspective. * After an outage or missed notifications, sweep recent orders that are still pending and refresh their status via the API. ### Configuration * Set your Callback URL in Merchant Portal → Settings → Shop Settings → Technical Information. Each shop has its own configuration. * Configure Sandbox and Production separately – ensuring test notifications never reach your production endpoint, and vice versa. ### Testing Validate your Webhook handling in the Sandbox environment before going live: * Successful, failed, cancelled, and abandoned payment scenarios – verify a notification is received and the order is updated correctly for each. * Refund scenarios – verify the refund-driven status change reaches your systems. * Duplicate delivery – verify that processing the same notification twice does not create duplicates. * Endpoint unavailability – take your endpoint down, complete a test payment, bring it back up, and verify recovery via API reconciliation. ### Frequently Asked Questions #### Do I need Webhooks if I use Hosted Checkout? Yes – the hosted page handles the customer experience, but your order processing still needs to know the payment outcome. The customer’s return to your site is not a payment confirmation. The Webhook or an API status query confirms it. #### Do I need Webhooks if I use a Web Plugin? Web Plugins include transaction status handling as part of their standard functionality. They process Webhooks and update order statuses. You do not implement an endpoint yourself. #### What happens if my server was down when a notification was sent? The gateway retries delivery automatically with increasing intervals. If all retries are exhausted, that notification is not sent again – reconcile via the Get Payment Information API and the Merchant Portal to catch up on any missed status changes. #### Can I receive the same notification twice? Yes – for example, if your endpoint responded slowly and a retry was triggered. Design your processing to be idempotent so a duplicate has no effect. #### How do I know a notification is genuine? Do not act on the notification content alone. Use it only as a trigger, and retrieve the payment details through the authenticated Get Payment Information API – the authoritative state always comes from the API, so a forged notification cannot cause an incorrect fulfilment. #### Which statuses will I be notified about? Every payment status change generates a notification – see Payment Statuses (Cards) and Pay by Bank › Payment Statuses for the status models and the recommended action per status. ### Related Documentation * [Payment Statuses (Cards)](/payment-methods/cards/payment-statuses.md) * [Pay by Bank › Payment Statuses](/payment-methods/pay-by-bank/payment-statuses.md) * [Unified Merchant API](/integration/merchant-api.md) * [Tokenization](/payment-methods/cards/tokenization.md) * [Merchant Portal](/guides/merchant-portal.md) * [Testing](/payment-methods/cards/testing.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.ecommerce.seb.ee/integration/merchant-api/webhooks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.