{"templateId":"GuidePage","sharedDataIds":{"sidebar":"sidebar-miniapps/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["callout"]},"type":"markdown"},"seo":{"title":"Webhooks","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":"webhooks","__idx":0},"children":["Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook"]}," object tells the platform how to process incoming HTTP requests from your provider. This is the core of event-driven integration."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Your webhook URL:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://{saas-api-url}/miniapps/{ns}/webhooks"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This URL is auto-generated and available as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{{webhookUrl}}"]}," in registration requests."]},{"$$mdtype":"Tag","name":"Callout","attributes":{"type":"info","title":"Not tenant webhooks"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["inbound"]}," provider webhooks (e.g. Salla → Karzoun). For ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["outbound"]}," workspace events to your own server, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developers/guides/webhooks"},"children":["Tenant webhooks"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"event-extraction","__idx":1},"children":["Event Extraction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Tells the platform ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["where to find the event name"]}," in the incoming webhook request."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Simple extraction"]}," (single field):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"webhook: {\n  eventExtraction: {\n    source: 'body',          // 'body', 'header', or 'query'\n    path: '$.event',         // JSONPath for body, or header/query key name\n  },\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Examples:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Salla sends ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"event\": \"order.created\", \"data\": {...} }"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source: 'body', path: '$.event'"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A service sends the event name in a header → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source: 'header', path: 'X-Event-Type'"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Composite extraction"]}," (multi-field):"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some providers split event identification across multiple fields. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["compositeStrategy"]}," to combine them:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"webhook: {\n  eventExtraction: {\n    // Primary path (ignored when compositeStrategy is present)\n    source: 'body',\n    path: '$.event',\n\n    // Combine multiple fields into one event string\n    compositeStrategy: {\n      parts: [\n        { source: 'header', path: 'X-GitHub-Event' },   // e.g., \"pull_request\"\n        { source: 'body', path: '$.action' },            // e.g., \"opened\"\n      ],\n      separator: '.',   // Result: \"pull_request.opened\"\n    },\n  },\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Another example — Slack uses body fields:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"compositeStrategy: {\n  parts: [\n    { source: 'body', path: '$.event.type' },      // e.g., \"message\"\n    { source: 'body', path: '$.event.subtype' },    // e.g., \"bot_message\"\n  ],\n  separator: '.',   // Result: \"message.bot_message\"\n},\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"transaction-deduplication","__idx":2},"children":["Transaction Deduplication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Prevents the same webhook from being processed twice (e.g., during retries)."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"webhook: {\n  transactionId: {\n    path: '$.data.id',       // Where to find a unique ID in the payload\n    fallback: 'generate',    // If not found, auto-generate a unique ID\n  },\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The platform checks Redis for the transaction ID. If it's already been processed, the webhook is silently acknowledged without re-processing."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Common patterns:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'$.data.id'"]}," — Salla order/cart ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'$.delivery'"]}," — GitHub delivery header"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'$.event_id'"]}," — Generic event ID field"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"verification-hmac-signatures","__idx":3},"children":["Verification (HMAC Signatures)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Verify that incoming webhooks genuinely come from your provider using HMAC signature verification."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"webhook: {\n  verification: {\n    type: 'hmac-sha256',              // 'hmac-sha256', 'hmac-sha1', 'header-token', 'none'\n    headerName: 'X-Signature-256',    // Header containing the signature\n    secretKey: 'webhookSecret',       // Key name to look up the secret value\n    timestampHeader: 'X-Timestamp',   // Optional: header with request timestamp\n  },\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verification types:"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hmac-sha256"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HMAC-SHA256 signature verification (recommended)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hmac-sha1"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HMAC-SHA1 signature verification"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["header-token"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Simple token comparison in header"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["none"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No verification (not recommended for production)"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["How the secret is resolved (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secretKey"]},"):"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secretKey"]}," field is a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["key name"]},", not the secret value itself. The platform resolves the actual secret using a two-source lookup:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Per-tenant credentials"]}," — Checks ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["installedMiniApps.credentials[secretKey]"]}," first. Use this when the provider issues a unique secret per connected store/tenant (e.g., registering a webhook returns a per-store signing key)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Global app config"]}," — Falls back to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["miniApp.auth.config[secretKey]"]}," if not found in tenant credentials. Use this when the provider uses a single global secret shared across all tenants (e.g., Salla, where the webhook secret is set once in the partner dashboard)."]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Secret Model"},"children":["Secret Model"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Where to store the value"},"children":["Where to store the value"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example Providers"},"children":["Example Providers"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Global (per-app)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auth.config.webhookSecret"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Salla, Shopify"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Per-tenant"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["installedMiniApps.credentials"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Slack, GitHub, custom"]}]}]}]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Tip:"]}," For global secrets, set the value in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auth.config"]}," of your MiniApp definition. For per-tenant secrets, store them in credentials during registration requests or the OAuth flow."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["How HMAC verification works:"]}]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Platform reads the signature from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["headerName"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Strips ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sha256="]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sha1="]}," prefix if present"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Resolves the secret via the two-source lookup described above"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Computes HMAC of the raw request body using the resolved secret"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Compares using timing-safe comparison to prevent timing attacks"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Rejects with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," if they don't match"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"challengehandshake-response","__idx":4},"children":["Challenge/Handshake Response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some providers (like Slack) require a challenge-response handshake when registering webhooks."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"webhook: {\n  challengeResponse: {\n    identifyField: 'type',              // Body field that identifies a challenge request\n    identifyValue: 'url_verification',  // Expected value for that field\n    challengePath: '$.challenge',       // Where to find the challenge token in the body\n    responseField: 'challenge',         // Field name in the response (optional)\n  },\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["How it works:"]}]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Provider sends a POST with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"type\": \"url_verification\", \"challenge\": \"abc123\" }"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Platform checks: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["body.type === 'url_verification'"]}," → yes, this is a challenge"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Platform extracts challenge token from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$.challenge"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"abc123\""]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Platform responds with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"challenge\": \"abc123\" }"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Provider considers the webhook URL verified"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["responseField"]}," is omitted, the challenge token is returned as the raw response body."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"customer-extraction","__idx":5},"children":["Customer Extraction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For MiniApps that receive customer data in webhooks (e-commerce platforms, CRMs), configure automatic customer creation/matching."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"webhook: {\n  customerExtraction: {\n    basePath: '$.data.customer',        // Base JSONPath to customer data\n    mapping: {\n      // Webhook field → Internal customer field\n      firstName: 'first_name',\n      lastName: 'last_name',\n      primaryEmail: 'email',\n      primaryPhone: 'mobile',\n      code: 'id',                       // External customer ID\n    },\n    // Override basePath for specific events\n    overrides: {\n      'customer.created': {\n        basePath: '$.data',             // Customer data is at root for this event\n      },\n      'abandoned.cart': {\n        basePath: '$.data.customer',    // Default path works, but explicit is fine\n      },\n    },\n  },\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Available customer fields:"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["firstName"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["First name"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastName"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Last name"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["primaryEmail"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Primary email address"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["primaryPhone"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Primary phone number"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["External customer ID (for matching)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["avatar"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Avatar URL"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sex"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Gender (numeric)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["birthDate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Date"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Date of birth"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["position"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Job position"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["department"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Department"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["state"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'visitor'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'lead'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'customer'"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["How it works:"]}," When a webhook arrives, the platform:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Extracts customer data from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["basePath"]}," (or override path for the specific event)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Maps provider field names to internal field names"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Calls ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["getOrCreateCustomer()"]}," which finds or creates the customer record"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Links the customer to the incoming event for automation context"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response-configuration","__idx":6},"children":["Response Configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Define what the platform sends back to your provider after receiving a webhook."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"webhook: {\n  response: {\n    statusCode: 200,\n    body: { ok: true },\n  },\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," The platform sends the response ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["immediately"]}," upon receiving the webhook, before async processing begins. This prevents provider timeouts. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202"]}," if your provider expects acknowledgment-style responses."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]}]},"headings":[{"value":"Webhooks","id":"webhooks","depth":1},{"value":"Event Extraction","id":"event-extraction","depth":2},{"value":"Transaction Deduplication","id":"transaction-deduplication","depth":2},{"value":"Verification (HMAC Signatures)","id":"verification-hmac-signatures","depth":2},{"value":"Challenge/Handshake Response","id":"challengehandshake-response","depth":2},{"value":"Customer Extraction","id":"customer-extraction","depth":2},{"value":"Response Configuration","id":"response-configuration","depth":2}],"frontmatter":{"title":"Webhooks","titleTranslationKey":"sidebar.miniapps.webhooks","audience":"developer","status":"published","locales":["en"],"template":"GuidePage","seo":{"title":"Webhooks"}},"lastModified":"2026-06-23T12:06:12.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/miniapps/guides/webhooks","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}