Copy page

Shared Guides

Webhooks

When Gett sends async order event requests to your system, every request includes signature headers for verification and follows a retry policy for reliability.

Webhook Events

Gett emits two event types over the order lifecycle. Both are delivered as POST requests to the webhook URL you register during integration setup.

Event type	When it fires	Timing
order_create	After a successful placeOrder — the Gett order has been accepted	Async — may arrive after the API response returns
order_update	When the order status changes (e.g., confirmed, shipped, fulfilled, canceled)	Async

order_create payload

Code
{
  "type": "order_create",
  "data": {
    "type": "order",
    "checkout_session_id": "csn_01hvz9kj0re0000000000000",
    "permalink_url": "https://gett.com/orders/018f4d2a-c5b0-7c4e-9b3a-2d1e8f7a6b5c",
    "status": "created",
    "refunds": []
  }
}

order_update payload

Code
{
  "type": "order_update",
  "data": {
    "type": "order",
    "checkout_session_id": "csn_01hvz9kj0re0000000000000",
    "permalink_url": "https://gett.com/orders/018f4d2a-c5b0-7c4e-9b3a-2d1e8f7a6b5c",
    "status": "confirmed",
    "refunds": []
  }
}

status values: created, manual_review, confirmed, canceled, shipped, fulfilled.

refunds[] shape (present when refunds have been applied):

Code
{
  "type": "store_credit",
  "amount": 1050
}

type is store_credit or original_payment. amount is in minor units (cents for USD — e.g. 1050 = $10.50).

---

Webhook Signatures

Every webhook request includes headers for signature verification:

Header	Value
Signature	base64( HMAC-SHA256( secret-as-UTF-8-bytes, "{Timestamp}.{rawBody}" ) )
Timestamp	RFC 3339 / ISO 8601 instant — e.g. 2026-06-17T17:34:56.1234567+00:00
API-Version	Protocol version: 2026-01-30 for ACP, 2026-03-01 for UCP. The value in the header is authoritative for that request.

The signed message is {Timestamp}.{rawBody} — the RFC 3339 timestamp string, a literal ., then the raw request body bytes. The secret is used as-is as raw UTF-8 bytes — it is not base64-decoded (this differs from the Standard Webhooks scheme used by the Commerce API). The resulting HMAC is base64-encoded (not hex). Use the Timestamp header to reject replays: discard any request whose timestamp is more than 300 seconds from the current time.

Verification Examples

TypeScript / Node.js

Code
import crypto from 'crypto';

function verifyWebhookSignature(
  rawBody: string,
  signature: string,
  timestamp: string,
  secret: string,
  toleranceSeconds = 300,
): boolean {
  // Replay protection: parse RFC 3339 timestamp and reject if too old
  const ts = Date.parse(timestamp);
  if (isNaN(ts) || Math.abs(Date.now() - ts) / 1000 > toleranceSeconds) return false;

  // Signed content is "{timestamp}.{rawBody}" — timestamp IS prepended
  const expected = crypto
    .createHmac('sha256', secret)           // secret used as raw UTF-8 string bytes
    .update(`${timestamp}.${rawBody}`, 'utf8')
    .digest('base64');                      // base64, NOT hex

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'base64'),
    Buffer.from(expected, 'base64'),
  );
}

// In your webhook handler:
app.post('/webhook/order', (req, res) => {
  const signature = req.headers['signature'] as string;
  const timestamp = req.headers['timestamp'] as string;
  if (!verifyWebhookSignature(req.rawBody, signature, timestamp, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  // Process the webhook...
});

Python

Code
import base64
import hashlib
import hmac
from datetime import datetime, timezone

def verify_webhook_signature(
    raw_body: bytes,
    signature: str,
    timestamp: str,
    secret: str,
    tolerance_seconds: int = 300,
) -> bool:
    # Replay protection: parse RFC 3339 timestamp and reject if too old
    ts = datetime.fromisoformat(timestamp)
    age = abs((datetime.now(timezone.utc) - ts).total_seconds())
    if age > tolerance_seconds:
        return False

    # Signed content is "{timestamp}.{rawBody}" — timestamp IS prepended
    # Secret is used as raw UTF-8 bytes — do NOT base64-decode it
    signed = timestamp.encode() + b"." + raw_body
    expected = base64.b64encode(
        hmac.new(secret.encode(), signed, hashlib.sha256).digest()
    ).decode()
    return hmac.compare_digest(signature, expected)

---

Retry Policy

Gett retries failed webhook deliveries with exponential backoff:

Attempt	Delay
1st retry	30 seconds
2nd retry	2 minutes
3rd retry	10 minutes
4th retry	1 hour
Final retry	6 hours

A delivery is considered failed if your endpoint returns a non-2xx status code or doesn't respond within 30 seconds.

---

Idempotency

Your webhook endpoints must be idempotent. Use the orderId as an idempotency key — if you receive a duplicate request, return 200 OK with the existing result rather than creating a duplicate.

---

Best Practices

• Return 200 OK as quickly as possible; process work asynchronously
• Store the orderId before returning the response
• Log all webhook payloads for debugging
• If you return a non-2xx response, the same webhook will be retried