Chapter 2 · API and integration
Webhooks: events and signature verification
Receiving signed notifications when an order changes status, and verifying them.
When an order changes status we send a signed POST request to your server. Webhooks are the fastest way to give your customer the result and to stop polling.
Set up
- Open Webhook in the panel.
- Enter your address in Webhook URL, for example
https://shop.example.com/partner/webhook. Onlyhttps, port 443 or 8443 and a public address are accepted. - Save. The Signing secret (
whsec_…) is shown only once — copy it into your server settings. - To turn webhooks off, clear the URL field and save.
If you lose the secret, press Create new secret — the old one stops working immediately.
Events
| Event | When |
|---|---|
order.pending |
The order was accepted |
order.processing |
Delivery has started |
order.completed |
The order is done; codes are in data.delivered |
order.failed |
The order failed and the money was returned |
The request
POST /partner/webhook HTTP/1.1
Content-Type: application/json
User-Agent: GOXOST-Partner-Webhooks/1.0
X-Partner-Event: order.completed
X-Partner-Delivery: whd_481
X-Partner-Signature: t=1763200934,v1=5f2c…
{ "id": "whd_481", "event": "order.completed", "created_at": "2026-11-15T10:02:14Z", "data": { …order… } }
data is the same order object the API returns.
Answer and retries
- Answer with any
2xxstatus within 5 seconds. Do the heavy work after you answer. - Redirects are not followed — use the final URL.
- Otherwise we retry after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h.
- The same delivery may arrive more than once — skip duplicates by
id. - Events may arrive out of order — trust
data.statusanddata.updated_at, not the arrival order.
The Webhook page lists Recent deliveries: event, number of attempts and status (Pending, Delivered, Failed).
Verify the signature
Check every webhook before you trust it. The X-Partner-Signature header holds t (timestamp) and v1. v1 is HMAC-SHA256 of "{t}.{raw body}" with your signing secret, hex encoded.
- Use the raw request body, before JSON parsing.
- Compare in constant time.
- Reject timestamps older than 5 minutes.
<?php
$body = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_PARTNER_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $header), $sig);
$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $body, getenv('PARTNER_WEBHOOK_SECRET'));
if (abs(time() - (int) ($sig['t'] ?? 0)) > 300 || ! hash_equals($expected, $sig['v1'] ?? '')) {
http_response_code(400);
exit;
}
$event = json_decode($body, true);
http_response_code(200);
import hashlib, hmac, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
sig = dict(part.split("=", 1) for part in header.split(","))
if abs(time.time() - int(sig.get("t", 0))) > 300:
return False
expected = hmac.new(secret.encode(), f"{sig['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, sig.get("v1", ""))
Never verify the signature against re-encoded JSON — even a changed space breaks the hash. A Node.js example is in the "Webhooks" chapter of the API docs.