> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hookstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools API

Backend endpoints for free developer tools — health check, scheduler, idempotency tester.

The Tools API powers hookstream's free developer tools at [hookstream.io/tools](https://hookstream.io/tools). These endpoints require no authentication but are IP rate-limited. They provide utility functions for webhook development: checking endpoint health, scheduling future webhook deliveries, and testing idempotency behavior.

## Health Check

POST `/v1/tools/health-check`

Check the health of a webhook endpoint by sending a test request and measuring the response.

**Authentication:** None (IP rate-limited).

### Body Parameters

The endpoint URL to check (`http` or `https`).

```bash cURL
curl -X POST https://hookstream.io/v1/tools/health-check \
  -H "Content-Type: application/json" \
  -d '{"url": "https://api.example.com/webhooks"}'
```

```json 200 OK
{
  "url": "https://api.example.com/webhooks",
  "status_code": 200,
  "latency_ms": 145,
  "headers": { "content-type": "application/json" },
  "body": "{\"ok\":true}",
  "healthy": true
}
```

## Schedule Webhook

POST `/v1/tools/schedule`

Schedule a webhook to be sent at a future time.

**Authentication:** None (IP rate-limited).

### Body Parameters

Destination URL for the scheduled webhook.

Delay in seconds before sending (1-86400).

HTTP method to use.

Custom headers to include.

Request body to send.

```bash cURL
curl -X POST https://hookstream.io/v1/tools/schedule \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks",
    "delay_seconds": 3600,
    "body": "{\"type\": \"reminder\", \"message\": \"Follow up\"}"
  }'
```

```json 201 Created
{
  "schedule_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "fires_at": "2026-03-02T09:00:00Z",
  "status": "pending"
}
```

## Get Schedule Status

GET `/v1/tools/schedule/:id`

Check the status of a scheduled webhook.

**Authentication:** None.

```json 200 OK
{
  "url": "https://api.example.com/webhooks",
  "method": "POST",
  "fires_at": "2026-03-02T09:00:00Z",
  "status": "completed",
  "response_status": 200,
  "completed_at": "2026-03-02T09:00:01Z"
}
```

## Idempotency Test

POST `/v1/tools/idempotency-test`

Send duplicate requests to test a webhook endpoint's idempotency behavior.

**Authentication:** None (IP rate-limited).

### Body Parameters

The endpoint URL to test.

Header name to use for idempotency (e.g., `Idempotency-Key`).

Value for the idempotency header.

Number of requests to send (2-10).

HTTP method.

Additional headers to include.

Request body to send.

Delay between requests in milliseconds (0-5000).

```bash cURL
curl -X POST https://hookstream.io/v1/tools/idempotency-test \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks",
    "idempotency_header": "Idempotency-Key",
    "idempotency_value": "order_123_create",
    "count": 3,
    "body": "{\"type\": \"order.created\", \"data\": {\"id\": \"ord_123\"}}"
  }'
```

```json 200 OK
{
  "url": "https://api.example.com/webhooks",
  "idempotency_header": "Idempotency-Key",
  "idempotency_value": "order_123_create",
  "total_requests": 3,
  "unique_responses": 1,
  "duplicate_responses": 2,
  "results": [
    { "attempt": 1, "status": 200, "latency_ms": 120, "response_body": "{\"ok\":true}", "is_duplicate": false },
    { "attempt": 2, "status": 200, "latency_ms": 95, "response_body": "{\"ok\":true}", "is_duplicate": true },
    { "attempt": 3, "status": 200, "latency_ms": 88, "response_body": "{\"ok\":true}", "is_duplicate": true }
  ]
}
```