HTTP Request
Make HTTP requests to external APIs and services directly from runbooks
Makes HTTP requests to external APIs and services, allowing runbooks to integrate with any system that exposes a REST API — without requiring a dedicated tool integration.
Overview
The HTTP Request tool is a general-purpose tool that gives your runbooks the ability to call external APIs. This is useful when you need to integrate with a service that Risotto doesn't have a built-in tool for, or when you want to interact with internal APIs and webhooks.
Common use cases include:
- Internal APIs: Query internal services for user data, asset information, or system status
- Webhooks: Trigger workflows in other platforms (e.g., CI/CD pipelines, notification systems)
- Third-party services: Interact with any SaaS product that offers a REST API
- Custom backends: Connect to your organization's internal tools and automation endpoints
How to Enable
In the Risotto dashboard, select Tools in the sidebar.
Add a new tool
In the Tool groups list, select HTTP (Advanced). Find Request HTTP Resource and click Set up.
Set the allowed domains
In Allowed Domains, add each domain the tool can call (for example,
api.example.com). This field is required.Configure credentials (optional)
If your target API requires authentication, set Authentication to Basic or Bearer and enter the credentials. To use a secret in a URL or header, add it under Secrets and refer to it as
{{ SECRET_NAME }}.Save the tool
Click Save.Use in a runbook
Reference the tool in any runbook. Risotto's agent will call the configured endpoint when the runbook executes.
Configuration Options
When configuring this tool in a runbook, you can set:
- URL - The full endpoint URL to send the request to. Write it as
https://<host>/<path>with an ASCII host and no backslash. Risotto refuses any other form with the error "URL is ambiguous". For an international domain name, use the punycode form. - Method - HTTP method to use (
GET,POST,PUT,PATCH,DELETE) - Headers - Key-value pairs for request headers (e.g.,
Authorization,Content-Type) - Body - Request body for
POST,PUT, andPATCHrequests (JSON format) - Timeout - Maximum time to wait for a response (default: 30 seconds)
Usage Examples
Example 1: Look up an asset in an internal CMDB
A runbook that checks your internal configuration management database when a user asks about a device:
Runbook instruction:
When a user asks about the status of a device, use the HTTP tool to look up the device in our asset inventory API.
What happens:
- The agent extracts the device identifier from the user's message
- Sends a
GETrequest to your internal API - Returns the device details to the user
Request:
GET https://cmdb.internal.company.com/api/v1/assets?hostname=LP-012345
Authorization: Bearer <configured-token>
Response used by the agent:
{
"hostname": "LP-012345",
"assigned_to": "jane.doe@company.com",
"model": "MacBook Pro 16-inch",
"os": "macOS 15.3",
"status": "active",
"warranty_expiry": "2027-06-15"
}
The agent then formats this information in its reply to the user in Slack.
Example 2: Create an incident in PagerDuty
A runbook that escalates urgent issues by creating a PagerDuty incident:
Runbook instruction:
If the user reports a critical production issue, use the HTTP tool to create a PagerDuty incident on the Infrastructure team's service.
Request:
POST https://api.pagerduty.com/incidents
Authorization: Token token=<configured-token>
Content-Type: application/json
{
"incident": {
"type": "incident",
"title": "Production database connection timeout",
"service": {
"id": "PXXXXXX",
"type": "service_reference"
},
"urgency": "high"
}
}
Response used by the agent:
{
"incident": {
"id": "PT4KHLK",
"status": "triggered",
"title": "Production database connection timeout",
"html_url": "https://company.pagerduty.com/incidents/PT4KHLK"
}
}
The agent confirms to the user that the incident was created and shares the link.
Example 3: Post a message to a Microsoft Teams webhook
A runbook that notifies a Teams channel when a specific type of request comes in:
Runbook instruction:
When a new hire access request is submitted, send a summary to the #onboarding channel in Teams.
Request:
POST https://company.webhook.office.com/webhookb2/...
Content-Type: application/json
{
"text": "New hire access request: Jane Doe (Engineering) needs access to GitHub, AWS, and Datadog. Requested by manager john.smith@company.com."
}
What It Can Do
- Make
GET,POST,PUT,PATCH, andDELETErequests - Send JSON request bodies
- Set custom headers, including authentication headers
- Read and parse JSON responses
- Handle standard HTTP status codes and surface errors to the agent
- Use values from the conversation context (e.g., the requester's email) in the request dynamically
Current Limitations
- JSON only — Request and response bodies must be JSON. File uploads, form-encoded data, and XML are not supported.
- No OAuth flows — The tool supports static credentials (API keys, bearer tokens) but cannot perform OAuth authorization code or client credentials flows on its own. Pre-generate tokens and provide them as headers.
- No pagination — The tool makes a single request and returns a single response. It does not automatically follow paginated results.
- No chaining — Each HTTP request is independent. The tool cannot use the response of one request as input to another within a single execution step.
- Response size — Large responses are truncated. The tool works best with APIs that return concise, focused payloads.
- Timeout — Requests that exceed the configured timeout (default 30 seconds) will fail. Long-running asynchronous operations are not supported.
- No retries — Failed requests are not automatically retried. The agent will report the failure and can be instructed to try again if appropriate.
Security Considerations
- Least privilege: Configure API tokens with the minimum scopes needed for the intended operations.
- Network access: The tool makes requests from Risotto's infrastructure. Ensure your target APIs allow inbound traffic from Risotto's IP ranges. Contact Risotto support for current IP addresses.
- Sensitive data: Be mindful of what data flows through requests and responses. Avoid sending or receiving PII unless necessary and compliant with your data policies.
- Audit logging: All HTTP tool executions are logged, including the URL, method, and response status code. Request and response bodies containing sensitive data are redacted in logs.
Troubleshooting
Request returns a 401 or 403 error
Possible causes:
- API token is expired or invalid
- Token doesn't have the required scopes or permissions
- IP allowlisting on the target API is blocking Risotto's requests
Solutions:
- Verify the token is still valid and has not been rotated
- Check the API's required scopes against your token's permissions
- Add Risotto's IP addresses to your API's allowlist
Request times out
Possible causes:
- The target API is unreachable from Risotto's infrastructure
- The endpoint is slow to respond
- DNS resolution is failing for internal hostnames
Solutions:
- Verify the URL is correct and the API is accessible from external networks
- Increase the timeout value in the tool configuration
- For internal APIs, put the API behind a public hostname (for example, a reverse proxy or an API gateway). Risotto refuses hosts that resolve to a private address, so an API that is only reachable over a VPN does not work
Response is truncated or missing data
Possible causes:
- The API returns a large payload that exceeds the tool's response size limit
- The API returns paginated results and only the first page is captured
Solutions:
- Add query parameters to limit the response (e.g.,
?limit=10,?fields=id,name,status) - Use API-specific filters to narrow results before the request is made
Agent doesn't use the tool as expected
Possible causes:
- The runbook instructions are too vague about when to use the tool
- The URL or parameters are not clearly defined in the runbook
Solutions:
- Be specific in your runbook instructions about when and how the HTTP tool should be used
- Include the exact URL pattern and expected parameters in the runbook
- Test the runbook in the Playground to verify the agent's behavior
Something wrong or missing? Report an issue · View as Markdown