Skip to Content
Webhooks

Webhooks

Webhooks deliver real-time notifications to your server when payment events occur. Instead of polling the API, register a webhook endpoint and Gatelithix will send HTTP POST requests with event data.

Setting Up Webhook Endpoints

Register a webhook endpoint via the API or admin portal. You will receive a webhook signing secret that you use to verify event authenticity.

curl -X POST https://sandbox.api.gatelithix.com/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wh_$(uuidgen)" \
  -d '{
    "url": "https://your-server.com/webhooks/gatelithix",
    "events": [
      "payment.authorized",
      "payment.captured",
      "payment.refunded",
      "payment.voided",
      "payment.failed"
    ]
  }'

Event Types

EventTrigger
payment.authorizedA payment authorization succeeded.
payment.capturedA payment was captured (settled).
payment.refundedA payment was refunded (full or partial).
payment.voidedAn authorization was voided (canceled).
payment.failedA payment attempt failed (decline, error).

Event Payload

{
  "id": "evt_a1b2c3d4e5f6",
  "type": "payment.captured",
  "created_at": "2026-03-18T12:00:01Z",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "merchant_id": "m1234567-89ab-cdef-0123-456789abcdef",
    "amount": 5000,
    "currency": "usd",
    "status": "succeeded",
    "connector_id": "stripe",
    "test_mode": true
  }
}

Signature Verification

Every webhook request includes a signature in the X-Gatelithix-Signature header. Verify this signature using HMAC-SHA256 to confirm the event was sent by Gatelithix and was not tampered with.

The signature format is: t=timestamp,v1=signature

Retry Behavior

If your endpoint returns a non-2xx status code or does not respond within 30 seconds, Gatelithix retries the delivery with exponential backoff:

AttemptDelay
1st retry1 minute
2nd retry5 minutes
3rd retry30 minutes
4th retry2 hours
5th retry24 hours

After all retries are exhausted, the event is moved to the dead letter queue (DLQ). You can replay DLQ events from the admin portal.

Best Practices

  • Respond quickly. Return a 200 status code as fast as possible. Process the event asynchronously if needed.
  • Make handlers idempotent. You may receive the same event more than once. Use the event id to deduplicate.
  • Verify signatures. Always validate the X-Gatelithix-Signature header before processing.
  • Use HTTPS. Webhook endpoints must use HTTPS in production.
  • Monitor failures. Check the admin portal for delivery failures and DLQ entries.
TokenizationHosted Fields