Sapience HTTP Tools for Web Hooks – Sapience Cloud

HTTP Tools Detailed Documentation

💡

The HTTP Tools Agent Feature for any Agent opens up a world of possibility. If you want a tutorial on how to use them, that’s not this article. This article is detailed documentation on how the system works, and is for advanced users.

Overview

There are two ways that you can build with Sapience and make it part of your toolkit:

Use Sapience as the orchestrator, and have it work with your automations and external apps (recommended). What this article is about.

Call Sapience’s API, and use Sapience inside your automations. This is the subject of a separate article.

Some Sapience Agents, including the default global “Sapience Agent” have an HTTP tools feature.

Under the hood, this is two separate tools designed for builders.

http_get tool: for simple flows and webhooks where you append data as querystring params

http_post tool: where you want to send a JSON or form-data payloads to the web-hook or APIs

This article focusses on using these to work with automations, but Sapience can actually use them to navigate any REST API. This is a very cool way to wire up Sapience to another system!

Important Note: the BEST way to use HTTP Tools is to wrap your instructions in a Sapience Skill. Hopefully you’re using those already, but if not, check this article:

Sapience Skills - A Superpower

HTTP GET Tool:

The HTTP GET tool lets your AI agent call external web services on your behalf. Think of it as giving your agent the ability to "visit a URL" and bring back whatever data is there.

This is one of the most powerful features in Sapience because it means your agent can:

Trigger automations in Make.com, n8n, Zapier, Power Automate, or any webhook-enabled platform

Fetch live data from external APIs

Connect to your own custom services

If you've read our Make.com + Sapience walkthrough, you've already seen this tool in action. This article goes deeper into how it works and what else you can do with it.

Key Things to know:

Name: The first tool is the http_get tool. You can refer to that explicitly in your prompts or in your skill files if you want to make certain it is invoked.

What: Makes an HTTP GET to a distant URL (e.g. web-hook).

Timeouts: Sets its timeout dynamically (the model decides), but has a max timeout value of 3 minutes, so you need to make sure your webhook/automation returns within that timeframe.

Here below we have asked the Sapience Agent how the HTTP GET tool works:

The Basics: What Happens When You Use http_get

When you ask your agent to call a URL, here's what happens behind the scenes:

You describe what you want in plain language

The agent recognizes it needs to make an HTTP request

Sapience calls the URL from our servers

The response comes back with status code, headers, and body data

The agent interprets the result and tells you what happened

The whole thing typically takes 1-3 seconds, depending on how fast the remote service responds.

How to Talk to Your Agent About It

You don't need to use any special syntax. Just describe what you want naturally:

Simple examples:

"Call this webhook: https://hook.make.com/abc123"

"Hit https://api.example.com/status and tell me what you get"

"Fetch the data from https://my-service.com/api/users"

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

Worked Example: Your First Webhook Call

Let's walk through a simple example to see how this works in practice.

Step 1: Get a webhook URL

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

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

Step 2: Ask Sapience to call it

Open a chat with any agent that has HTTP tools enabled (the Sapience Agent has this by default), and type:

"Call this Make.com webhook for me: https://hook.us1.make.com/abc123def456ghi789"

Step 3: See the result

The agent will respond with something like:

"I called that webhook and got back:

That's it! You just got Sapience to trigger an external automation.

Passing Data to Your Webhook

Most of the time, you'll want to send data along with your webhook call. With HTTP GET, data goes in the query string - the part after the ? in the URL.

The format

https://your-webhook.com/endpoint?param1=value1&param2=value2

The ? starts the query string

Each key=value pair is separated by &

Example with data

Let's say your Make.com webhook expects taskName and notes parameters:

"Call this webhook with task data: https://hook.make.com/abc123?taskName=Review Q1 Report&notes=Need by Friday"

The agent will call that URL, and Make.com will receive:

taskName = "Review Q1 Report"

notes = "Need by Friday"

Pro tip: Let the agent build the URL

You can also just tell the agent what data to send:

"Call my Make.com webhook at https://hook.make.com/abc123 and pass taskName='Review Q1 Report' and notes='Need by Friday'"

The agent is smart enough to construct the proper URL for you.

HTTP POST Tool

POST’ing, either JSON or Form Data is a little more complex, so its got its own dedicated article here:

HTTP POST Tool for Web Hooks

API & URL Authentication: Calling Protected APIs or Endpoints

Many APIs require authentication - a way to prove you're allowed to access them. The http_get tool supports four types of authentication.

Bearer Tokens (Most Common)

Used by: Stripe, OpenAI, most modern APIs

A bearer token is like a password that goes in the request header. You'll usually get this from the service's dashboard or API settings.

How to use it:

"Call https://api.stripe.com/v1/customers using bearer token 'sk_test_abc123xyz'"

The agent adds Authorization: Bearer sk_test_abc123xyz to the request headers automatically.

API Key in Header

Used by: Many webhook services, custom APIs

Some services want you to put an API key in a specific header (like X-API-Key).

How to use it:

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

API Key in Query String

Used by: Some older APIs, simple services

Some services want the API key right in the URL.

How to use it:

"Call https://api.example.com/data?api_key=my-key-123"

Or let the agent build it:

"Call https://api.example.com/data with API key 'my-key-123' as a query parameter"

Basic Authentication

Used by: Older systems, some enterprise APIs

Basic auth uses a username and password.

How to use it:

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

The agent will encode the credentials properly and add them to the Authorization header.

Understanding the Response

When the agent calls a URL, it reports back several pieces of information:

What	What It Means
Status Code	200 = success, 404 = not found, 401 = authentication failed, 500 = server error
Body	The actual data returned (often JSON)
Time	How long the request took

Status Code	Meaning	What to do
200	Success!	Everything worked
201	Created	Your request created something (also success)
400	Bad request	Check your parameters - something's wrong with the data you sent
401	Unauthorized	Your authentication failed - check your token/key
403	Forbidden	You're authenticated but not allowed to access this
404	Not found	The URL doesn't exist - check for typos
500	Server error	The remote service had a problem (not your fault)

Timeouts: When Things Take a While

By default, the tool waits 30 seconds for a response. If you're calling something slow, you can request a longer timeout (up to 180 seconds):

"Call https://slow-api.com/process with a 60 second timeout"

If the request times out, the agent will tell you and you can try again with a longer timeout.

What http_get and http_post Do NOT Do

It's important to understand the boundaries:

If you want to...	Use this instead
Read the content of a webpage	`fetch_web_content` - extracts readable text
Search the web for information	`web_research` - searches and summarizes
Send a POST request with a body	Coming soon! For now, use querystring parameters or build a Make.com scenario

Tips for Best Results

1. Be explicit about what you want

Good:

"Call https://api.example.com/users and show me the JSON response"

Less good:

"Check that URL"

2. Tell the agent about expected responses

If you know what the webhook returns, mention it:

"Call my webhook - it should return JSON with a 'success' field"

This helps the agent interpret the response correctly.

3. Handle errors gracefully

If something fails, ask the agent to diagnose:

"That didn't work - can you tell me more about the error?"

4. Test webhooks in the browser first

Before asking Sapience to call a webhook, paste it in your browser to make sure it's working. This saves debugging time.

Combine with Sapience Skills

The absolute best way to use these tools is with a custom Sapience Skill. There you can define in great detail how to call the automation or API you are working with, what the shape of the data payload to send and receive is, or anything else relevant to making your automation work well.

Security Notes

A few things to keep in mind:

Your tokens are sensitive - Don't share chat transcripts that contain API keys or tokens

Requests come from Sapience - The target sees requests from our servers, not your computer

Only public URLs work - Internal/corporate network URLs won't be accessible unless you are a Sapience Private Cloud customer.

Quick Reference: Prompt Templates

Copy these and customize for your needs:

Simple call:

"Call [URL] and tell me what you get back"

With query parameters:

"Call [URL]?param1=value1&param2=value2"

With bearer token:

"Call [URL] with bearer token '[YOUR-TOKEN]'"

With API key in header:

"Call [URL] with API key '[KEY]' in the [HEADER-NAME] header"

With longer timeout:

"Call [URL] with a 60 second timeout"

What's Next?

Now that you understand the HTTP Tools Agent Feature, here are some ideas:

Connect Sapience to Make.com - See our full walkthrough

Trigger n8n workflows - Same concept, just use your n8n webhook URLs

Build a data pipeline - Have Sapience analyze files, then send results to an external system

Monitor services - Ask Sapience to check if your APIs are responding

The HTTP Tools Feature opens up a world of integrations. Have fun exploring!