Skip to content

Chapter 2 · API and integration

Webhooks: events and signature verification

Receiving signed notifications when an order changes status, and verifying them.

3 min read

On this page
  1. Set up
  2. Events
  3. The request
  4. Answer and retries
  5. Verify the signature

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

  1. Open Webhook in the panel.
  2. Enter your address in Webhook URL, for example https://shop.example.com/partner/webhook. Only https, port 443 or 8443 and a public address are accepted.
  3. Save. The Signing secret (whsec_…) is shown only once — copy it into your server settings.
  4. 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 2xx status 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.status and data.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.

Was this article helpful?

Didn’t find an answer?

Send a request — a specialist will check your account and reply.