# 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

1. **Navigate to the Tools page**

   In the Risotto dashboard, select **Tools** in the sidebar.

2. **Add a new tool**

   In the **Tool groups** list, select **HTTP (Advanced)**. Find **Request HTTP
   Resource** and click **Set up**.

3. **Set the allowed domains**

   In **Allowed Domains**, add each domain the tool can call (for example,
   `api.example.com`). This field is required.

4. **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 }}`.

5. **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`, and `PATCH` requests (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:**

1. The agent extracts the device identifier from the user's message
2. Sends a `GET` request to your internal API
3. 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:**

```json
{
  "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
```

```json
{
  "incident": {
    "type": "incident",
    "title": "Production database connection timeout",
    "service": {
      "id": "PXXXXXX",
      "type": "service_reference"
    },
    "urgency": "high"
  }
}
```

**Response used by the agent:**

```json
{
  "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
```

```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`, and `DELETE` requests
- 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

> **Warning:** The HTTP Request tool is designed for simple API integrations. For complex
> workflows with multi-step authentication flows, consider using a dedicated
> tool integration or contacting Risotto support.

- **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

> **Note:** All credentials configured in the HTTP Request tool (headers, tokens) are
> encrypted at rest using Risotto's encryption service. They are never exposed
> to end users or included in Slack messages.

- **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](https://www.tryrisotto.com/docs/dashboard/knowledge/playground) to verify the agent's behavior

Source: https://www.tryrisotto.com/docs/integrations/tools/http/make_request
