HTTP POST Tool for Web Hooks – Sapience Cloud

HTTP POST Tool

💡

If you haven’t already - read the main page for HTTP Tools first. It covers general concepts, and the HTTP GET tool.

Overview

The HTTP POST tool lets your AI agent send data to external web services. While the http_get tool is for fetching data, http_post is for sending data - think submitting forms, creating records, or triggering workflows with complex payloads.

This is essential when you need to:

Send structured JSON data to Make.com, n8n, or Zapier webhooks

Create or update records via REST APIs

Submit form data to external services

Trigger automations with complex payloads that won't fit in a URL

Important: HTTP tools work as a cluster - when http_post is enabled, http_get is automatically enabled too. You get both or neither.

The Difference Between GET and POST

http_get	http_post
Retrieves data	Sends data
Data goes in the URL (query string)	Data goes in the request body
Limited data size (~2000 characters)	Large payloads supported
Best for: webhooks, API reads, triggers	Best for: form submissions, creating records, complex data

When to use http_post:

Your webhook expects a JSON body

You're sending more than a few simple parameters

The API documentation says "POST" for the endpoint

You need to create or update something (not just read)

How to Talk to Your Agent About It

Just describe what you want naturally:

Simple examples:

"POST this JSON to https://hook.make.com/abc123: {"task": "Review report", "priority": "high"}"

"Send this data to my webhook: name=John, email=john@example.com"

"Submit to https://api.example.com/users with body: {"firstName": "Jane", "lastName": "Doe"}"

The agent will figure out that you want to make an HTTP POST request.

Worked Example: Sending JSON to a Webhook

Step 1: Get your webhook URL

If you're using Make.com, create a scenario with a Webhook trigger that expects JSON. Make.com will give you a URL like:

https://hook.us1.make.com/abc123def456ghi789

Step 2: Ask Sapience to POST to it

Open a chat with any agent that has HTTP tools enabled, and type:

"POST this JSON to https://hook.us1.make.com/abc123def456ghi789: {"customerName": "Acme Corp", "orderTotal": 1500, "items": ["Widget A", "Widget B"]}"

Step 3: See the result

The agent will respond with something like:

"I sent that data to your webhook and got back:

Content Types: JSON vs Form Data

The http_post tool supports two common formats for sending data:

JSON (Default)

Most modern APIs expect JSON. This is the default.

How to use it:

"POST JSON to https://api.example.com/data: {"key": "value"}"

The tool automatically sets Content-Type: application/json.

Form Data

Some older services expect form-encoded data (like traditional HTML forms).

How to use it:

"POST form data to https://api.example.com/submit: field1=value1&field2=value2"

Or ask the agent to use form encoding:

"Send username=john and password=secret as form data to https://api.example.com/login"

Authentication: Same as http_get

The http_post tool supports the same four authentication types:

Bearer Tokens (Most Common)

"POST to https://api.stripe.com/v1/charges using bearer token 'sk_test_abc123' with body: {"amount": 1000}"

API Key in Header

"Send JSON to https://api.service.com/data with API key 'my-key-123' in the X-API-Key header"

API Key in Query String

"POST to https://api.example.com/create?api_key=my-key-123 with body: {"name": "Test"}"

Basic Authentication

"POST to https://api.example.com/secure with username 'admin' and password 'secret123'"

Understanding the Response

When the agent POSTs data, it reports back the same information as http_get:

What	What It Means
Status Code	200/201 = success, 400 = bad data, 401 = auth failed, 500 = server error
Body	The response data (often contains the created record or confirmation)
Time	How long the request took

Common status codes for POST

Code	Meaning	What to do
200	Success!	Your data was accepted
201	Created	A new record was created (common for REST APIs)
400	Bad request	Check your JSON format or required fields
401	Unauthorized	Your authentication failed
422	Unprocessable	The server understood but can't process (validation error)
500	Server error	The remote service had a problem

Tips for Best Results

1. Be explicit about the format

Good:

"POST this JSON to [URL]: {"name": "value"}"

Less good:

"Send name=value to that URL"

2. Use proper JSON formatting

Make sure your JSON is valid:

Use double quotes for keys and string values: {"key": "value"}

Numbers don't need quotes: {"count": 42}

Booleans are lowercase: {"active": true}

3. Tell the agent what response to expect

"POST to my webhook - it should return a JSON object with an 'id' field"

4. Test your webhook first

Use a tool like Postman or curl to verify your endpoint works before asking Sapience.

Timeouts

By default, the tool waits 30 seconds for a response. For slow endpoints:

"POST to https://slow-api.com/process with a 120 second timeout and body: {"data": "large payload"}"

Maximum timeout is 180 seconds.

What http_post Does NOT Do

If you want to...	Use this instead
Just fetch data from a URL	`http_get`
Read webpage content	`fetch_web_content`
Upload files	Not currently supported
Make PUT/DELETE requests	Not currently supported

Quick Reference: Prompt Templates

Simple JSON POST:

"POST to [URL] with body: {"key": "value"}"

Form data POST:

"POST form data to [URL]: field1=value1&field2=value2"

With bearer token:

"POST to [URL] with bearer token '[TOKEN]' and body: {"data": "here"}"

With API key:

"POST to [URL] with API key '[KEY]' in header [HEADER-NAME]"

With longer timeout:

"POST to [URL] with 60 second timeout and body: {...}"

Combining GET and POST in Workflows

Since both tools are always enabled together, you can build multi-step workflows:

"First, use http_get to fetch the user list from https://api.example.com/users. Then use http_post to send a summary of the results to my webhook at https://hook.make.com/abc123"

What's Next?

Now that you understand both HTTP tools:

Build complex automations - Fetch data, process it, send results somewhere else

Create records via REST APIs - Add users, orders, tickets to external systems

Integrate with any webhook platform - Make.com, n8n, Zapier, Power Automate

Connect to custom services - Your own APIs and microservices

The HTTP tools give you full control over external integrations. Happy building!