Agent API Reference

The Agent API exposes hookstream's webhook testing infrastructure with agent-friendly aliases under https://hookstream.io/v1/agent/*. It's the same surface as /v1/test/sessions — same rate limits, same lifetime, same features — but named and documented for programmatic use by AI agents.

No authentication required. Rate limited to 10 sessions per IP per hour. Sessions live for 14 days or 2,000 requests, whichever comes first. Sessions can be graduated into a full hookstream account later — no data is lost.

If your agent needs higher limits, longer retention, or access to the full platform (connections, destinations, transforms, metrics), create a free hookstream account and use an API key with the regular REST API. The Agent API is designed for zero-friction prototyping and ephemeral workflows.

Base URL

text
https://hookstream.io/v1/agent/sessions

The same endpoints are also mounted at https://hookstream.io/v1/test/sessions — use whichever feels clearer in your code.

Typical agent workflow

Endpoints

Create a session

POST https://hookstream.io/v1/agent/sessions

Creates a new ephemeral webhook endpoint. No body required, no auth.

Response

json
{
  "session_id": "abc123...",
  "url": "https://hookstream.io/v1/ingest/abc123...",
  "expires_at": "2026-03-16T00:00:00.000Z",
  "request_limit": 2000,
  "request_count": 0
}

List events for a session

GET https://hookstream.io/v1/agent/sessions/:id

Returns session metadata and received events. Supports filtering and pagination.

Response

json
{
  "session": {
    "id": "abc123...",
    "url": "https://hookstream.io/v1/ingest/abc123...",
    "expires_at": "2026-03-16T00:00:00.000Z",
    "request_count": 5
  },
  "events": [
    {
      "id": "evt_...",
      "method": "POST",
      "headers": { "content-type": "application/json" },
      "body": "{\"type\":\"order.created\"}",
      "received_at": "2026-03-02T12:00:00.000Z"
    }
  ],
  "pagination": { "has_more": false }
}

Configure custom response

PATCH https://hookstream.io/v1/agent/sessions/:id/response

Set what hookstream returns to webhook senders that hit this endpoint.

Example request

json
{
  "status_code": 200,
  "content_type": "application/json",
  "body": "{\"ok\": true}"
}

Configure forwarding

PATCH https://hookstream.io/v1/agent/sessions/:id/forwarding

Real-time relay of incoming webhooks to another URL. Runs in waitUntil, so it doesn't block ingest.

Example request

json
{ "url": "https://my-app.com/webhooks" }

Export events

GET https://hookstream.io/v1/agent/sessions/:id/export

Dumps all session events.

Delete a session

DELETE https://hookstream.io/v1/agent/sessions/:id

Removes the session and all its events. Idempotent.

Full example: agent creates a session, sends a webhook, and checks events

# 1. Create session
SESSION=$(curl -s -X POST https://hookstream.io/v1/agent/sessions)
URL=$(echo $SESSION | jq -r '.url')
ID=$(echo $SESSION | jq -r '.session_id')

# 2. Send a test webhook
curl -X POST $URL \
  -H 'Content-Type: application/json' \
  -d '{"type": "order.created", "data": {"id": "ord_123"}}'

# 3. Check what landed
curl -s "https://hookstream.io/v1/agent/sessions/$ID" | jq '.events'

// 1. Create an ephemeral endpoint
const res = await fetch("https://hookstream.io/v1/agent/sessions", {
  method: "POST",
});
const { session_id, url } = await res.json();
console.log("Webhook URL:", url);

// 2. Send a test webhook
await fetch(url, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ type: "order.created", data: { id: "ord_123" } }),
});

// 3. Fetch received events
const eventsRes = await fetch(
  `https://hookstream.io/v1/agent/sessions/${session_id}`,
);
const { events } = await eventsRes.json();
console.log(`Received ${events.length} events`);

import requests

base = "https://hookstream.io/v1/agent/sessions"

# 1. Create session
session = requests.post(base).json()
session_id, url = session["session_id"], session["url"]
print("Webhook URL:", url)

# 2. Send a test webhook
requests.post(
    url,
    json={"type": "order.created", "data": {"id": "ord_123"}},
)

# 3. Fetch events
events = requests.get(f"{base}/{session_id}").json()["events"]
print(f"Received {len(events)} events")

Full-account access for agents

If your agent needs the full platform — connections, transforms, destinations, metrics, real-time streaming — create a free account and issue an API key. Then the agent can hit the full REST API at https://hookstream.io/v1/* with an X-API-Key header.

const API = "https://hookstream.io/v1";
const headers = {
  "X-API-Key": process.env.HOOKSTREAM_API_KEY,
  "Content-Type": "application/json",
};

// Create a source
const source = await fetch(`${API}/sources`, {
  method: "POST",
  headers,
  body: JSON.stringify({ name: "My Agent Source" }),
}).then((r) => r.json());

// Fetch recent events
const events = await fetch(`${API}/events?limit=20`, { headers }).then((r) =>
  r.json(),
);

// Open a real-time WebSocket stream (token via query param)
const ws = new WebSocket(
  `wss://hookstream.io/v1/ws?token=${process.env.HOOKSTREAM_API_KEY}`,
);
ws.addEventListener("message", (ev) => {
  console.log("event:", JSON.parse(ev.data));
});

import os, requests

API = "https://hookstream.io/v1"
headers = {
    "X-API-Key": os.environ["HOOKSTREAM_API_KEY"],
    "Content-Type": "application/json",
}

# Create a source
source = requests.post(
    f"{API}/sources",
    headers=headers,
    json={"name": "My Agent Source"},
).json()

# Fetch recent events
events = requests.get(f"{API}/events?limit=20", headers=headers).json()
print(f"Fetched {len(events['data'])} events")

API keys are plain HTTP headers, so they work with every agent framework — LangChain tool specs, OpenAI function calls, Anthropic tool use, MCP servers, and bespoke agents alike. No SDK required.

Rate limits and lifetime

• 10 sessions per IP per hour on session creation
• 2,000 requests per session — after that, new webhooks are rejected
• 14-day TTL — sessions expire automatically; data is cleaned up by a Cron job
• Early deletion via DELETE .../:id
• Graduation — calling POST /v1/test/sessions/:id/claim with an authenticated session moves the session and all its events into the user's organization. The webhook URL keeps working.

Session graduation

An ephemeral session can become a persistent source. When a user signs up and authenticates, calling POST https://hookstream.io/v1/test/sessions/:id/claim attaches the session to their org. The url stays identical, all received events come with it, and it shows up as a regular source in the dashboard. This is useful when an agent prototype graduates into production.

Related

• AI & LLM Integration
• Skills & IDE Integration
• Webhook Testing guide