Gale uses webhooks to notify your system in real time when key events occur, such as checkout status changes or product eligibility updates.

​
Endpoint Configuration

To receive events, configure a publicly reachable HTTPS URL in the Gale Dashboard. Gale will send signed JSON payloads to this endpoint.
  • Method: POST
  • Content-Type: application/json
  • Header: X-Gale-Signature

​
Signature Verification

All webhook requests are signed using HMAC-SHA256 to ensure authenticity.

​
Header format:

X-Gale-Signature: t=1623945600,v1=7f83b1657ff1fc...

​
How to verify:

  1. Extract the t (timestamp) and v1 (signature) values.
  2. Prepend the timestamp and raw request body with a period (.):
    t + "." + raw_body
  3. Hash this string using your webhook signing secret (found in the dashboard).
  4. Compare the result to v1 using a timing-safe comparison.

​
Events

​
checkoutStatusChange

{
  "event": "checkoutStatusChange",
  "checkout_id": "chk_123",
  "status": "PAID",
  "amount_cents": 6050,
  "currency": "usd",
  "timestamp": "2025-06-05T12:04:12Z"
}
Status values: UNPAID, PAID, REFUNDED, CANCELLED, EXPIRED

​
productStatusChange

{
  "event": "productStatusChange",
  "product_id": "prod_abc123",
  "eligibility_type": "not_eligible",
  "timestamp": "2025-06-05T13:15:00Z"
}
Eligibility values: sigis_eligible, lmn_eligible, vision_eligible, not_eligible

​
Retry Policy

AttemptDelay
1Immediate
230 seconds
32 minutes
410 minutes
After four failed attempts, the event is marked as dead-lettered. You can manually resend from the Dashboard. Ensure you return a 200 OK response within 5 seconds to avoid retries.