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

# Test Sessions

Ephemeral webhook testing sessions with inspection, forwarding, and export.

Test sessions provide ephemeral webhook endpoints for testing and debugging. Sessions are created without authentication and last for **14 days or 2000 requests** (whichever comes first). Each session gets a unique ingestion URL and a real-time WebSocket feed.

Sessions support custom response configuration, webhook forwarding, event notes, and NDJSON/CSV export. Authenticated users can **claim** sessions to make them permanent.

Most test session endpoints require no authentication — they're designed for quick, frictionless testing. Only the claim endpoint requires auth. Sessions are rate-limited by IP address.

## Create Session

POST `/v1/test/sessions`

Create a new ephemeral test session. Returns the session with its ingestion URL.

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

```bash cURL
curl -X POST https://hookstream.io/v1/test/sessions
```

```json 201 Created
{
  "session_id": "a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8",
  "url": "https://hookstream.io/v1/ingest/a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8",
  "expires_at": "2026-03-15T12:00:00Z",
  "request_limit": 2000,
  "request_count": 0
}
```

## Retrieve Session

GET `/v1/test/sessions/:id`

Get a test session with its received events.

**Authentication:** None.

```json 200 OK
{
  "session": {
    "id": "a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8",
    "url": "https://hookstream.io/v1/ingest/a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8",
    "expires_at": "2026-03-15T12:00:00Z",
    "request_limit": 2000,
    "request_count": 5,
    "created_at": "2026-03-01T12:00:00Z"
  },
  "events": [
    {
      "id": "evt_001",
      "source_id": "a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8",
      "method": "POST",
      "headers": "{\"content-type\":\"application/json\"}",
      "content_type": "application/json",
      "received_at": "2026-03-01T12:05:00Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  }
}
```

## Claim Session

POST `/v1/test/sessions/:id/claim`

Claim a test session, converting it from ephemeral to permanent and associating it with your organization.

**Authentication:** API key or session cookie.

```bash cURL
curl -X POST https://hookstream.io/v1/test/sessions/a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8/claim \
  -H "X-API-Key: $HOOKSTREAM_API_KEY"
```

```json 200 OK
{
  "id": "ts_a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8",
  "claimed": true,
  "org_id": "org_abc123",
  "source_id": "src_eph_a3b4c5d6e7f8a9b0"
}
```

## Delete Session

DELETE `/v1/test/sessions/:id`

Delete a test session and all its events.

**Authentication:** None.

```json 200 OK
{ "deleted": true }
```

## Retrieve Event

GET `/v1/test/sessions/:id/events/:event_id`

Get full details for a specific event in a test session, including the resolved payload.

**Authentication:** None.

```json 200 OK
{
  "id": "evt_001",
  "source_id": "a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8",
  "method": "POST",
  "headers": "{\"content-type\":\"application/json\"}",
  "content_type": "application/json",
  "payload": { "test": true },
  "received_at": "2026-03-01T12:05:00Z"
}
```

## Configure Custom Response

PATCH `/v1/test/sessions/:id/response`

Configure the custom response returned when webhooks hit this session's ingestion URL.

**Authentication:** None.

### Body Parameters

HTTP status code to return (200-599).

Response content type.

Custom response body (max 4KB).

```bash cURL
curl -X PATCH https://hookstream.io/v1/test/sessions/a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8/response \
  -H "Content-Type: application/json" \
  -d '{
    "status_code": 201,
    "content_type": "application/json",
    "body": "{\"received\":true}"
  }'
```

```json 200 OK
{ "ok": true }
```

## Configure Forwarding

PATCH `/v1/test/sessions/:id/forwarding`

Configure webhook forwarding — incoming webhooks are forwarded to the target URL in addition to being recorded.

**Authentication:** None.

### Body Parameters

Target URL to forward webhooks to. Set to `null` to disable.

```bash cURL
curl -X PATCH https://hookstream.io/v1/test/sessions/a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8/forwarding \
  -H "Content-Type: application/json" \
  -d '{"url": "http://localhost:3000/webhooks"}'
```

```json 200 OK
{
  "ok": true,
  "forwarding": "http://localhost:3000/webhooks"
}
```

## Set Event Note

PUT `/v1/test/sessions/:id/events/:eid/note`

Add or update a note on a specific event in a test session.

**Authentication:** None.

### Body Parameters

Note text to attach to the event.

```bash cURL
curl -X PUT https://hookstream.io/v1/test/sessions/a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8/events/evt_001/note \
  -H "Content-Type: application/json" \
  -d '{"note": "This is the successful payment event"}'
```

```json 200 OK
{ "ok": true }
```

## Export Events

GET `/v1/test/sessions/:id/export`

Export all events from a test session as NDJSON or CSV.

**Authentication:** None.

### Query Parameters

Export format: `ndjson` or `csv`.

```text 200 OK
{"id":"evt_001","method":"POST","body":{"test":true},"received_at":"2026-03-01T12:05:00Z"}
{"id":"evt_002","method":"POST","body":{"test":false},"received_at":"2026-03-01T12:06:00Z"}
```