From 67a1f638cd244864de10ce9cef468527d5ffff4f Mon Sep 17 00:00:00 2001 From: virgoone Date: Tue, 13 Oct 2026 13:51:07 +0900 Subject: [PATCH 1/3] docs(agents): explain JSON escaping of webhook body placeholders Co-Authored-By: Claude Opus 5.5 (1M context) --- agents/build/dynamic-variables.mdx | 3 ++- agents/build/webhook-tools.mdx | 24 ++++++++++++++++++++++++ 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/agents/build/dynamic-variables.mdx b/agents/build/dynamic-variables.mdx index ee88d3d..a7e773c 100644 --- a/agents/build/dynamic-variables.mdx +++ b/agents/build/dynamic-variables.mdx @@ -132,7 +132,8 @@ Custom variables also render inside [webhook tool](/agents/build/webhook-tools#a https://ehr.example.com/patients/{{patient_id}}/appointments?clinic={{clinic_id}} ``` -- In the URL the value is URL-encoded, like argument values. In header values and the body template it is inserted as is. Numbers render as written, booleans as `true` or `false`. +- In the URL the value is URL-encoded, like argument values. In header values it is inserted as is. Numbers render as written, booleans as `true` or `false`. +- In a JSON body, a value inside a string is JSON-escaped, like argument values. See [Values in a JSON body](/agents/build/webhook-tools#values-in-a-json-body). - When the tool declares an argument with the same name as a custom variable, the argument wins: that placeholder is filled from what the agent supplies. - A placeholder with no value renders as an empty string in the request, unlike in the prompt, where it stays visible. diff --git a/agents/build/webhook-tools.mdx b/agents/build/webhook-tools.mdx index 51ef9a6..1541a96 100644 --- a/agents/build/webhook-tools.mdx +++ b/agents/build/webhook-tools.mdx @@ -51,6 +51,30 @@ https://api.example.com/orders/{{order_number}} } ``` +### Values in a JSON body + +When the body is JSON, the platform keeps it valid. What happens to a value depends on where its placeholder sits: + +- **Inside a JSON string**, like `"note": "{{note}}"`: the value is JSON-escaped. Quotes, backslashes, and line breaks in it can't break the body. +- **Outside a string**, like `"count": {{count}}`: the value is inserted as is. Use this to send a number, a boolean, or a whole object. + +```json Body template +{ + "note": "{{note}}", + "count": {{count}} +} +``` + +If the agent passes `She said "call me back"` as `note`, the request body contains `"note": "She said \"call me back\""`. + +The same rule covers arguments, dynamic variables, and requests from the **Test** tab. + +The body counts as JSON when its content type is `application/json` (the default) or a `+json` type such as `application/vnd.api+json`. A `Content-Type` header on the tool takes priority over the content type setting. Bodies of any other content type are filled in as is. + + +A placeholder outside a string is not checked. If its value isn't valid JSON in that spot, the body isn't either. Put text values in quotes. + + ## Authentication headers Each header has a kind that identifies what it carries: From dca83f7ddf762b68a9b98e926eac8ce24293d5e4 Mon Sep 17 00:00:00 2001 From: virgoone Date: Thu, 15 Oct 2026 10:21:01 +0900 Subject: [PATCH 2/3] docs(agents): drop the blanket JSON-validity claim for webhook bodies Only values inside JSON strings are escaped. A placeholder outside a string is inserted as is, as the section already says. Co-Authored-By: Claude Opus 5.5 (1M context) --- agents/build/webhook-tools.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agents/build/webhook-tools.mdx b/agents/build/webhook-tools.mdx index 1541a96..5608171 100644 --- a/agents/build/webhook-tools.mdx +++ b/agents/build/webhook-tools.mdx @@ -53,7 +53,7 @@ https://api.example.com/orders/{{order_number}} ### Values in a JSON body -When the body is JSON, the platform keeps it valid. What happens to a value depends on where its placeholder sits: +When the body is JSON, what happens to a value depends on where its placeholder sits: - **Inside a JSON string**, like `"note": "{{note}}"`: the value is JSON-escaped. Quotes, backslashes, and line breaks in it can't break the body. - **Outside a string**, like `"count": {{count}}`: the value is inserted as is. Use this to send a number, a boolean, or a whole object. From 11ceb7be98273f492aa2b9402b642b80cce52156 Mon Sep 17 00:00:00 2001 From: virgoone Date: Mon, 19 Oct 2026 14:26:52 +0900 Subject: [PATCH 3/3] chore: update OpenAPI schema --- api-reference/openapi.json | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 5905b01..aefd15b 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -66,6 +66,19 @@ "title": "Finished At", "type": "string" }, + "anchor_day": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "default": null, + "description": "UTC day of month used for credit refreshes; clamp to the month's last day. Missing/null falls back to updated_at's UTC day.", + "title": "Anchor Day" + }, "stripe_subscription_id": { "anyOf": [ { @@ -24699,6 +24712,11 @@ ], "default": null, "title": "Channel" + }, + "world_context": { + "default": false, + "title": "World Context", + "type": "boolean" } }, "required": [