{"templateId":"GuidePage","sharedDataIds":{"sidebar":"sidebar-miniapps/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Best practices","description":"Developer API, partner integration, MCP, SDK, and customer help center.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"best-practices","__idx":0},"children":["Best practices"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication","__idx":1},"children":["Authentication"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Always list secrets in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sensitiveKeys"]}," — they are never sent to the browser"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use OAuth 2.0 with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auto_refresh: true"]}," when your provider issues refresh tokens"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store webhook signing secrets in credentials or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auth.config"]}," and reference via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secretKey"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Document which values tenants must provide vs Karzoun-managed OAuth client IDs"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"actions","__idx":2},"children":["Actions"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["renderStrategy: 'auto'"]}," so forms generate from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parameters"]}," JSON Schema"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use RPC sources (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-source"]},") for IDs users should not paste manually"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Always set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-fallback: 'input'"]}," when RPC sources may fail"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Chain requests when later steps need IDs from earlier responses"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use array ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mapping"]}," on intermediate requests, object ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mapping"]}," on the final response"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"triggers","__idx":3},"children":["Triggers"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Match the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["exact event string"]}," your webhook extraction produces"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Write clear ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}," text for the Automation Builder"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://lucide.dev/icons"},"children":["Lucide"]}," icon names for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["icon"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webhooks","__idx":4},"children":["Webhooks"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Require HMAC verification in production (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hmac-sha256"]}," when supported)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionId"]}," to deduplicate provider retries"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Respond with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response.statusCode: 200"]}," and a minimal body — Karzoun acknowledges quickly"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"e-commerce","__idx":5},"children":["E-commerce"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/miniapps/guides/sync"},"children":["sync"]}," for bulk import and realtime handlers"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Align ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sync.webhooks.handlers"]}," keys with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["triggers[].event"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["joinCodes"]}," for discount arrays and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mapItems"]}," for line items"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerExtraction.overrides"]}," when customer JSON differs per event"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"security--submission","__idx":6},"children":["Security & submission"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Do not embed tenant production secrets in submitted JSON"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Document sandbox test accounts for reviewers"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keep ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["docsUrl"]}," pointed at your integration guide for end users"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Bump ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["version"]}," on every approved change"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Rate limiting (30 requests / 60 seconds per user per app) is enforced on action execution automatically."]}]},"headings":[{"value":"Best practices","id":"best-practices","depth":1},{"value":"Authentication","id":"authentication","depth":2},{"value":"Actions","id":"actions","depth":2},{"value":"Triggers","id":"triggers","depth":2},{"value":"Webhooks","id":"webhooks","depth":2},{"value":"E-commerce","id":"e-commerce","depth":2},{"value":"Security & submission","id":"security--submission","depth":2}],"frontmatter":{"title":"Best practices","titleTranslationKey":"sidebar.miniapps.bestPractices","audience":"developer","status":"published","locales":["en"],"template":"GuidePage","seo":{"title":"Best practices"}},"lastModified":"2026-06-23T12:06:12.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/miniapps/guides/best-practices","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}