Webhooks

A webhook is an HTTP POST request that Ginger Payments sends to your server every time the status of an order changes. Webhooks keep your system up to date without constant polling, and they matter most when your customer doesn't come back to your website after paying, for example because they closed the browser.

The Quickstart shows a complete webhook handler in Node.js and Python.

Set the webhook URLCopy Anchor Link

You can set the webhook URL in two places:

curl https://api.dev.gingerpayments.com/v1/orders/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "currency": "EUR",
    "amount": 995,
    "merchant_order_id": "EXAMPLE001",
    "description": "Example order",
    "return_url": "https://www.example.com/order/EXAMPLE001",
    "webhook_url": "https://www.example.com/webhook"
  }'

What you receiveCopy Anchor Link

Ginger Payments sends a POST request with a JSON body to your webhook URL:

POST /webhook HTTP/1.1
Host: www.example.com
Content-Type: application/json

{
  "event": "status_changed",
  "order_id": "4c6afd74-a840-4aab-b411-1e6e0636d341",
  "project_id": "b5f39273-44e7-4385-8e08-44612ef3e117"
}

The webhook deliberately doesn't contain the status. Retrieve the order with GET /v1/orders/{order_id}/ and act on the status in that response, so you only act on data that comes from Ginger Payments directly. See Order and transaction status.

Respond to the webhookCopy Anchor Link

Respond with HTTP status 200 OK. The response body can be empty: Ginger Payments ignores it.

Delivery counts as failed when:

• your server responds with a 4xx or 5xx status code;
• connecting to your webhook URL times out;
• reading the response from your server times out;
• your server refuses the connection.

The timeout for connecting and reading is 4 seconds for the first attempt and 10 seconds for every retry. Respond quickly: if you need to do heavy work, store the notification and process it in the background.

RetriesCopy Anchor Link

After a failed delivery, Ginger Payments retries the webhook every 2 minutes. After the 10th failed attempt, Ginger Payments stops trying.

Best practicesCopy Anchor Link

• Make your handler idempotent. Because of retries, you can receive the same notification more than once. Processing it twice must not, for example, ship an order twice.
• Always fetch the order. Never derive the status from the webhook itself.
• Have a backup. A webhook can be delayed or lost. Regularly retrieve orders that aren't final yet, as described in When to check.
• Allow the traffic. If a firewall, WAF or bot protection runs in front of your server, make sure it doesn't block webhook requests.
• Use HTTPS for your webhook URL.