Skip to content
MiniApps/
Best practices
Last updated

Best practices

Authentication

  • Always list secrets in sensitiveKeys — they are never sent to the browser
  • Use OAuth 2.0 with auto_refresh: true when your provider issues refresh tokens
  • Store webhook signing secrets in credentials or auth.config and reference via secretKey
  • Document which values tenants must provide vs Karzoun-managed OAuth client IDs

Actions

  • Use renderStrategy: 'auto' so forms generate from parameters JSON Schema
  • Use RPC sources (x-source) for IDs users should not paste manually
  • Always set x-fallback: 'input' when RPC sources may fail
  • Chain requests when later steps need IDs from earlier responses
  • Use array mapping on intermediate requests, object mapping on the final response

Triggers

  • Match the exact event string your webhook extraction produces
  • Write clear label and description text for the Automation Builder
  • Use Lucide icon names for icon

Webhooks

  • Require HMAC verification in production (hmac-sha256 when supported)
  • Set transactionId to deduplicate provider retries
  • Respond with response.statusCode: 200 and a minimal body — Karzoun acknowledges quickly

E-commerce

  • Use sync for bulk import and realtime handlers
  • Align sync.webhooks.handlers keys with triggers[].event
  • Use joinCodes for discount arrays and mapItems for line items
  • Use customerExtraction.overrides when customer JSON differs per event

Security & submission

  • Do not embed tenant production secrets in submitted JSON
  • Document sandbox test accounts for reviewers
  • Keep docsUrl pointed at your integration guide for end users
  • Bump version on every approved change

Rate limiting (30 requests / 60 seconds per user per app) is enforced on action execution automatically.

Previous page
Next page