Skip to content
MiniApps/
Troubleshooting
Last updated

Troubleshooting

Issues you may hit while building a MiniApp definition before or during Karzoun review.

Marketplace & submission

MiniApp not visible after approval

  • Only Karzoun can set status: 'public' — keep status: 'private' in your draft
  • Confirm approval email and correct ns in Marketplace search
  • Partner-only apps may be restricted to specific tenants

Submission rejected for schema errors

  • Validate required fields in document schema
  • Ensure ns is unique, lowercase, kebab-case
  • List every secret field in auth.sensitiveKeys

Authentication

OAuth popup does not close

  • Redirect URI must be exactly {SAAS_API_URL}/miniapps/{ns}/oauth2
  • Check browser console for postMessage errors from the OAuth window

Actions return 401

  • Verify [[accessToken]] mapping in get_token.mapping
  • For OAuth, confirm refresh_token config and auto_refresh: true
  • Test the same request with curl using sandbox credentials

Webhooks & triggers

Automations never fire

  • triggers[].event must match the string produced by webhook.eventExtraction exactly
  • Register webhook URL with provider: {SAAS_API_URL}/miniapps/{ns}/webhooks
  • Enable signature verification only after confirming secret resolution path

Signature verification fails

  • Confirm secretKey resolves from credentials vs auth.config (global vs per-tenant)
  • Compare raw body bytes — re-serialized JSON will not match HMAC

RPC sources

Dropdowns empty

  • Test source.rpc_* URL manually with a valid token
  • Check dataPath, valueField, and labelField against live JSON
  • Provide x-fallback: 'input' so users can paste IDs when RPC fails

E-commerce sync

Orders not appearing

  • Prefer sync.webhooks.handlers over legacy webhook.ecommerce
  • Handler recordType must be order or abandonedCart
  • mapping.code must extract a stable external ID
  • Include sample webhook payloads in your submission

Getting help

Include in support requests:

  1. MiniApp ns and version
  2. Redacted JSON definition
  3. Sample webhook payload and expected event name
  4. Provider sandbox account (if available)

Contact: developers@karzoun.chat or your Karzoun partner manager.

Previous page