Going Live

Production checklist

1. 1

   Use a dedicated production project & key

   Create a separate project for production and retire any key used during development or shared in chat, tickets, or commits. The plaintext key is shown exactly once when you create or rotate it — capture it then. Store it in a secret manager, keep it server-side only, and never commit it. Rotating a key invalidates the old one immediately.
2. 2

   Verify every webhook signature

   Reject any webhook whose X-Zyra-Signature doesn't verify against your project's webhook signing secret (from the project's webhook settings in the dashboard). Never trust a payload you haven't verified — see Webhooks.
3. 3

   Handle every webhook event type

   Your endpoint should accept and gracefully handle checkout.paid, checkout.underpaid, checkout.overpaid, checkout.created, wallet.created, and deposit — and return 2xx for any unrecognized type rather than erroring, so new event types never wedge delivery. Don't forget the under- and overpayment paths.
4. 4

   Make your consumers idempotent

   A webhook may be delivered more than once. De-duplicate on data.transactionId or data.checkoutId and make fulfillment a no-op the second time. Likewise, send an Idempotency-Key on every checkout and wallet request — see Advanced.
5. 5

   Reconcile — don't rely on delivery alone

   Webhook delivery is retried but not guaranteed to be exactly-once. For anything critical, if an expected event hasn't arrived, fetch the checkout's current status from the API (GET /v1/checkout/{checkoutId}) and reconcile, rather than assuming the webhook will always land.
6. 6

   Monitor your endpoint

   Log and alert on webhook handler failures and 5xx spikes on your receiver. A failing endpoint silently delays fulfillment, so treat its health like any other critical dependency.