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

urlstringrequiredbody

The endpoint URL to check (http or https).

bash
curl -X POST https://hookstream.io/v1/tools/health-check \  -H "Content-Type: application/json" \  -d '{"url": "https://api.example.com/webhooks"}'
json
{  "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

urlstringrequiredbody

Destination URL for the scheduled webhook.

delay_secondsnumberrequiredbody

Delay in seconds before sending (1-86400).

methodstringbodydefault: POST

HTTP method to use.

headersobjectbody

Custom headers to include.

bodystringbody

Request body to send.

bash
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
{  "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
{  "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

urlstringrequiredbody

The endpoint URL to test.

idempotency_headerstringrequiredbody

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

idempotency_valuestringrequiredbody

Value for the idempotency header.

countnumberrequiredbody

Number of requests to send (2-10).

methodstringbodydefault: POST

HTTP method.

headersobjectbody

Additional headers to include.

bodystringbody

Request body to send.

delay_msnumberbody

Delay between requests in milliseconds (0-5000).

bash
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
{  "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 }  ]}
Previous Ingest
Next WebSockets