Skip to content

Webhook Payload Format

When a tool with webhook execution type is called, the system sends a POST request to your configured URL.

Request to Webhook

The request body is exactly the tool arguments generated by the model.

POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token> (if configured in `tool_execution_config.headers`)

{
  "location": "San Francisco, CA"
}

For a different tool schema, the body shape changes to match that tool's parameters.

Quick Test with curl

curl -X POST "https://your-webhook-url" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <optional-token>" \
  -d '{
    "location": "San Francisco, CA"
  }'

Response Handling

Your endpoint can return either JSON or plain text.

  • If response is valid JSON, the parsed JSON is returned to the model.
  • If response is not JSON, raw text is returned to the model.
  • If the webhook times out, returns HTTP error (4xx/5xx), or fails, the tool returns an error object.

Example success response:

{
  "temperature": 72,
  "condition": "Sunny",
  "location": "San Francisco, CA"
}

Example error response from runtime on timeout/failure:

{
  "error": "Webhook timed out after 30s"
}

Runtime Defaults

  • Default timeout is 30 seconds unless tool_execution_config.timeout is set.
  • Headers come from tool_execution_config.headers and are sent as-is.
  • Each tool call is logged to activity logs as tool_call with request URL, arguments, latency, and status.

Best Practices

  • Keep webhook responses fast and deterministic.
  • Return JSON when possible so the model can consume structured data.
  • Use tool_execution_config.headers for auth tokens and tenant headers.
  • Validate tool inputs server-side and return clear error messages.