Copy page

Shared Guides

Webhooks

When Gett sends webhook requests to your system (e.g., order placement), 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 two headers for signature verification:

Header	Value
Signature	HMAC-SHA256 of the raw request body, hex-encoded
Timestamp	Unix timestamp (seconds) of when the event was signed
API-Version	Protocol version, currently 2026-01-30

The Signature is HMAC-SHA256 of the raw request body, computed using the webhook secret provided during your integration setup. Compare against the body alone — do not prepend the timestamp. Use the Timestamp header to reject replays: discard any request whose timestamp is more than 300 seconds away 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: reject stale timestamps
  const ts = parseInt(timestamp, 10);
  if (Math.abs(Date.now() / 1000 - ts) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');

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

// 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 hmac
import hashlib
import time

def verify_webhook_signature(
    raw_body: bytes,
    signature: str,
    timestamp: str,
    secret: str,
    tolerance_seconds: int = 300,
) -> bool:
    ts = int(timestamp)
    if abs(time.time() - ts) > tolerance_seconds:
        return False
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    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