Documentation

Zotlo: API-confirmed webhooks guide

Checked against Zotlo's official documentation on 2026-10-27. Zotlo webhooks carry no cryptographic signature. The only controls Zotlo documents are optional IP/domain allowlisting and a queue.requestID delivery ID (webhook overview). AnalyticFast confirms payment hints through the authenticated API. Refund hints are rejected until an authenticated refund contract can be verified.

1. verify() accepts queue.eventType=transaction and reads parameters.transaction_id. It rejects refund hints and malformed IDs before any network call.
2. It calls GET https://api.zotlo.com/v1/transaction/detail?transactionId=…&isSandbox=… with the site's own AccessKey/AccessSecret headers (API introduction, Get Payment Details). The call times out after 10 seconds.
3. It requires meta.httpStatus 200, the exact transaction_id, a documented lifecycle status, and a matching transactionLog entry whose requestType is transaction and code is S0000001. A successful detail lookup alone does not prove a payment succeeded; Zotlo also returns details for failed attempts (payment result codes).
4. parse() reads only the API-confirmed transaction: price (decimal major units), currency, status, purchase_date, package_id and subscriptionId. Price and currency are never taken from the webhook body.

The settings URL includes a private ?hook=... capability visible only to owners/admins after saving credentials. Missing, wrong and cross-site capabilities fail before consuming the shared API lookup budget. Saving credentials rotates this URL, including when the same credentials are saved again: update Zotlo after every save. Treat the entire URL as a secret. Invocation URL logging is disabled in Wrangler; application logs omit queries. Authenticated payment verification and provider/transaction idempotency still apply.

Mapping

• A price of 0 records nothing. A positive-price trial backed by the success log is recorded. renewal maps to a renewal; the other documented paid actions (trial, start_paid, trial_to_paid, reactive, consumable) map to a payment. Unknown actions fail closed.
• Refunds: the authenticated API's refund object has no documented amount/time structure (payment details). Reading refund_price or refund_date from the unsigned webhook lets an attacker corrupt the ledger. Refund webhooks therefore fail closed with 401. Reconcile confirmed refunds using a site-scoped payments:write token and POST /api/v1/payments from a trusted backend; see server API. Record both the original payment and its refunds under the same server API transaction namespace, and disable the native Zotlo payment feed for those transactions to prevent double counting. Do not enable Zotlo revenue reporting until that reconciliation is installed and tested. Obtain an authenticated refund payload/schema from Zotlo before implementing automatic refunds; do not guess its fields or treat a truthy refund as a full refund.
• subscriber_id (an email or phone number) is never stored. A SHA-256 hash prefixed zs_ becomes the provider customer ID, so repeat purchases still correlate.
• Zotlo dates have no time zone and are read as UTC.

Setup

Paste the credentials from Zotlo Developer Tools → API Keys as AccessKey:AccessSecret. Append :sandbox for a sandbox project. They're encrypted at rest like every provider secret, and used only to read transaction details. Point only the Payments webhook at /api/webhooks/zotlo/<siteId>. Configure trusted server refund reconciliation separately.

Hosted checkout (hosted checkout) has no documented arbitrary metadata query parameters, so visitors are attributed by return-page claim or timing. The tracker never writes analytics IDs into Zotlo's subscriber identity fields.

Unverified

No live Zotlo account was used. The sandbox isSandbox=true base URL behavior, and the exact shape of transaction.refund, haven't been tested against Zotlo itself. Before relying on revenue numbers, run one sandbox purchase and one refund (Phase 4).