Test Sessions

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 -X POST https://hookstream.io/v1/test/sessions

json
{
  "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
{
  "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 -X POST https://hookstream.io/v1/test/sessions/a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8/claim \
  -H "X-API-Key: $HOOKSTREAM_API_KEY"

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

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

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

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

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

text
{"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"}