Response Mapping

Response mapping lets you extract specific values from a webhook's JSON response and store them as named variables. Instead of working with the entire raw response, you pick out just the fields you need. For example, your API returns a full order object with orderId, status, tracking number, estimated delivery, internal notes, and metadata. With response mapping, you configure three simple rules: extract 'data.orderId' as 'orderId', extract 'data.status' as 'status', and extract 'data.eta' as 'eta'. Now the rest of your system — workflows, AI responses, subsequent actions — only sees those three clean values instead of the entire JSON blob. This is especially useful when working with APIs that return large or deeply nested responses. You get exactly what you need, nothing more.

Response mapping is essential in three scenarios. First, when using webhook data in workflow steps: after a webhook executes in a workflow, subsequent steps can access the mapped values as variables. For example, you might call a lead enrichment API and then route the lead based on the company size returned. Second, when extracting specific fields from AI-callable webhook responses: the mapped data is what the AI uses to answer the user's question. Precise mapping means the AI gets exactly the data it needs — no more, no less. Third, when chaining actions together: feed data from one webhook into another. For example, use a first webhook to get an order ID, then pass that order ID to a second webhook that checks shipping status. Without response mapping, the extracted values would not be available as structured variables for downstream use.

Each response mapping has three fields. The JSONPath field specifies which value to extract from the response — it uses JSONPath syntax starting with '$' as the root (e.g., '$.data.orderId' extracts the orderId field nested inside data). The Variable Name field is the name you want to assign to the extracted value — this becomes the variable name available in workflows (prefixed with 'webhook_') or in AI responses. Keep it short and descriptive. The Default Value field is optional — if the JSONPath resolves to nothing (the field is missing or null), this fallback value is used instead. This prevents null errors in downstream logic. You can add multiple mappings to a single webhook. Each one extracts a different value from the same response. For example, you might have three mappings: one for order ID, one for status, and one for estimated delivery date — all extracted from the same API response.

JSONPath is the syntax for navigating JSON responses. Here are the most common patterns. '$.status' extracts a top-level field — use this for simple flat responses. '$.data.results[0].id' reaches into a nested object, then grabs the first item in an array and extracts its 'id' field — useful for API responses that wrap results in a data envelope. '$.items[*].name' extracts the 'name' field from every item in an array — returns a list of values. '$.meta.pagination.total' navigates deeply nested objects to reach a specific value. The '$' always represents the root of the response. Use dots to navigate into objects and square brackets with indices for arrays. The wildcard '[*]' means 'all items in this array'. Most APIs return data in predictable structures, so once you identify the pattern, mapping becomes straightforward. Tip: use the test webhook feature to see the actual response structure, then write your JSONPath expressions based on the real data.

Mapped data is used differently depending on the context. In workflows, all mapped variables are automatically prefixed with 'webhook_'. So if you mapped a variable named 'orderId', it becomes available as 'webhook_orderId' in subsequent workflow steps. You can use these variables in conditions (e.g., if webhook_revenue > 1000000, route to enterprise sales), in messages, or as inputs to other actions. In AI-callable webhooks, response mapping works together with response filtering. The filter is applied first to narrow down array results, then the mapped values are what the AI sees and uses to formulate its answer. Default values are particularly important for AI-callable webhooks — if a field is missing, the default prevents the AI from receiving null data, which could lead to confusing responses. A practical example: you map 'status' with a default of 'unknown'. If the API fails to return a status field, the AI can still tell the user 'The current status is unknown' rather than erroring out.