Troubleshooting

Reading the delivery log

In the merchant app, go to Settings → Integrations → Webhooks, tap an endpoint, then View Deliveries.

Each row shows:

• Event type — what event triggered the delivery
• Status indicator — green (success), yellow (pending/failed), red (exhausted)
• HTTP status — the response code your server returned
• Attempt count — how many times Loyalite tried

Tap a delivery for full details including the error message, last HTTP status, and next retry timestamp.

Common errors

connection refused / connection timeout

Cause: Loyalite can't reach your server.

Fix:

• Verify the endpoint URL is correct and publicly reachable from the internet.
• Check your firewall rules — make sure inbound HTTPS (port 443) is allowed from Loyalite's servers.
• If using a local dev server, use a tunnel like ngrok (opens in a new tab) or Cloudflare Tunnel (opens in a new tab) to expose it.
• Confirm TLS is configured correctly (valid certificate, not expired).

HTTP 401 / 403 — Unauthorized

Cause: Your server is rejecting the request, usually due to signature verification failure.

Fix:

• Confirm you're using the correct signing secret (the one shown at endpoint creation or after the last rotation).
• Make sure you're computing the HMAC over the raw request body, not over parsed JSON. JSON re-serialization may change whitespace.
• Use a constant-time comparison for the signature check.
• If you recently rotated your secret, make sure your server's WEBHOOK_SECRET environment variable is updated.

HTTP 400 / 422 — Bad Request

Cause: Your server rejected the payload as invalid.

Fix:

• Loyalite payloads are well-formed JSON — check your server's request parsing logic.
• Don't validate unknown event type fields strictly — future event types may have additional fields; use lenient parsing.
• Return 200 for event types you don't handle rather than 400 or 422.

HTTP 500 — Internal Server Error

Cause: An unhandled exception in your webhook handler.

Fix:

• Check your server's application logs for the stack trace.
• Wrap your handler in a try/catch and always return 200 (or 500 if you want retries) with a meaningful error logged.
• Common cause: null reference when accessing data fields for an unexpected event type.

HTTP 402 — Payment Required (from Loyalite's POS API)

Note: This status comes from your calls to Loyalite's POS API (/webhook/redeem), not from your webhook endpoint.

Cause: Your Loyalite subscription has expired or is no longer active.

Fix:

• Open the merchant app → Account → Subscription to renew or reactivate.
• The /webhook/pos (earn) endpoint is not subscription-gated. Only /webhook/redeem returns 402.

HTTP 429 — Rate Limited

Cause: Your server is rate-limiting Loyalite's requests.

Fix:

• Loyalite delivery workers respect standard HTTP semantics — if you return 429, the delivery is retried according to the retry schedule.
• Consider whitelisting Loyalite's delivery server IPs, or removing rate limiting for your /webhooks/ path.

Deliveries succeed but Zapier/Make doesn't trigger

Cause: The Zapier/Make.com scenario isn't listening at the right time.

Fix:

• Zapier: Click Test trigger in the Zap editor while Loyalite sends a test event.
• Make.com: Click Run once before sending the test event.
• Verify the Zapier/Make URL in the Loyalite delivery log matches what Zapier/Make shows.

Using the test delivery

The Test action sends a real HTTP POST with a synthetic payload. Use it to:

• Confirm your endpoint URL is reachable
• Debug signature verification in isolation
• Inspect the exact JSON shape

Test deliveries appear in the delivery log and use the same retry mechanism as real deliveries.

Delivery appears as exhausted

All 6 attempts failed. Steps:

1. Tap the delivery in the merchant app to read the last error message and HTTP status.
2. Fix the root cause — network issue, server crash, or invalid signature logic.
3. After fixing, send a new test delivery to confirm the endpoint is healthy.
4. Future events will start delivering again — exhausted deliveries are not re-queued automatically.

Endpoint shows as inactive

An inactive endpoint receives no deliveries. Check the endpoint in the merchant app:

1. Go to Settings → Integrations → Webhooks.
2. Tap the endpoint → Edit.
3. Toggle Active back on.

Confused by stamp.redeemed vs coupon.redeemed?

These are two distinct events:

A typical sequence: customer earns stamps → card fills → stamp.redeemed fires (coupon created) → customer returns → presents coupon → coupon.redeemed fires.

See Event Reference for full payload schemas of both events.

Still stuck?

Contact support at [email protected] with:

• The endpoint URL
• The delivery ID from the delivery log
• The HTTP status and error message shown