Skip to content

API Reference: Requests

TypeScript SDK reference for requests: list, search, wait, replay and export, plus provider detection, body parsing, payload schemas and request diffing.

Updated Nov 2026

Part of the TypeScript SDK API reference. The constructor, endpoints and direct delivery are on the first page.

Requests

GET/endpoints/:slug/requests

client.requests.list

List captured requests for an endpoint.

list(endpointSlug: string, options?: ListRequestsOptions): Promise<Request[]>
ParamTypeRequiredDescription
endpointSlugstringyesEndpoint slug
limitnumbernoMax results (default: 50)
sincenumbernoOnly return requests after this timestamp (ms)
kind"http" | "email"noOnly HTTP requests, or only emails
GET/endpoints/:slug/requests

client.requests.listPaginated

List captured requests with cursor-based pagination.

listPaginated(slug: string, options?: ListPaginatedRequestsOptions): Promise<PaginatedResult<Request>>
ParamTypeRequiredDescription
slugstringyesEndpoint slug
limitnumbernoMax results per page
cursorstringnoCursor from previous page
kind"http" | "email"noOnly HTTP requests, or only emails
GET/requests/:id

client.requests.get

Get a single captured request by ID. For a captured email, kind is "email" and email holds the parsed message; client.emails.get() returns the same request typed as an EmailRequest.

get(requestId: string): Promise<Request>

When the endpoint has layouts, parsed holds what they found once the parse is done.

GET/requests/:id/raw

client.requests.raw

A captured email's exact message (RFC 5322 bytes), and attachment() one of its attachments by its index in email.attachments, from 0 to 99. Both work for emails kept in storage (email.stored).

raw(requestId: string): Promise<Uint8Array>
attachment(requestId: string, index: number): Promise<AttachmentDownload> // { bytes, filename, contentType }
POST/requests/:id/replay

client.requests.redeliver

Send a captured request through its endpoint's destinations again, with their current settings. True when at least one delivery was queued. To send it to one destination only, use forwarding.redeliver().

redeliver(requestId: string): Promise<boolean>
GET/endpoints/:slug/requests

client.requests.waitFor

Poll for incoming requests until one matches or timeout expires. Accepts human-readable duration strings.

waitFor(endpointSlug: string, options?: WaitForOptions): Promise<Request>
ParamTypeRequiredDescription
endpointSlugstringyesEndpoint slug to monitor
timeoutnumber | stringnoMax wait time: ms or "30s", "5m", "1h" (default: 30000)
pollIntervalnumber | stringnoInterval between polls (default: 500)
match(request) => booleannoFilter function
sincenumbernoOnly consider requests after this timestamp in ms (default: 5 minutes ago)

The five-minute lookback means a request that arrived just before the call is still found. Pass since: Date.now() to wait only for new requests.

GET/endpoints/:slug/requests

client.requests.waitForAll

Wait for multiple matching requests to arrive.

waitForAll(slug: string, options: WaitForAllOptions): Promise<Request[]>
ParamTypeRequiredDescription
slugstringyesEndpoint slug
countnumberyesNumber of requests to collect
timeoutnumber | stringnoMax wait time
match(request) => booleannoFilter function
sincenumbernoOnly consider requests after this timestamp (ms)
GET/api/stream/:slug

client.requests.subscribe

Stream incoming requests via SSE as an async iterator.

subscribe(slug: string, options?: SubscribeOptions): AsyncIterable<Request>
ParamTypeRequiredDescription
slugstringyesEndpoint slug
signalAbortSignalnoSignal to cancel the subscription
timeoutnumber | stringnoMax stream duration
reconnectbooleannoAuto-reconnect on disconnect
maxReconnectAttemptsnumbernoMax reconnection attempts (default: 5)
reconnectBackoffMsnumber | stringnoBase backoff between reconnects (default: 1000)
idleTimeoutnumber | stringnoTreat the stream as dead after this long without data (default: "90s"; 0 turns it off)
onReconnect(attempt) => voidnoCalled before each reconnect attempt

Streamed requests carry kind, so you can tell emails apart, but not the parsed email. Read it with client.emails.get(request.id).

POST/requests/:id/replay

client.requests.replay

Replay a captured request to a target URL. Sends the original method, headers, and body. Hop-by-hop headers are stripped. Throws for a captured email, which is not an HTTP request; to post an email to a handler, send client.emails.toJson(email) with sendTo().

replay(requestId: string, targetUrl: string): Promise<Response>
ParamTypeRequiredDescription
requestIdstringyesID of the captured request
targetUrlstringyesURL to send the replayed request to
GET/requests/search

client.requests.search

Search captured requests across endpoints for text.

q matches as a case-insensitive substring of the path, the headers or the body (% and _ are literal), and an email also matches on its decoded subject, text and sender and recipient addresses; a request id finds that request first. Each result's id is the request's own id, the one requests.get() takes.

There is no text index behind search, so the server reads a long history newest first, in pages of about 2 seconds. search() follows the cursor for you until it has limit matches (50 by default), the whole range was read, or 25 seconds have passed, and returns the matches found by then. A rare term on a very long history can therefore return fewer matches than exist; searchPage() says how far a search read and lets you continue it.

search(filters?: SearchFilters): Promise<SearchResult[]>
ParamTypeRequiredDescription
slugstringnoFilter by endpoint slug
methodstringnoFilter by HTTP method
kind"http" | "email"noOnly HTTP requests, or only emails
qstringnoText to find (substring)
fromstring | numbernoStart time (duration or timestamp)
tostring | numbernoEnd time (duration or timestamp)
limitnumbernoMax results (default: 50)
offsetnumbernoMatches to skip
order"asc" | "desc"noSort order (default: "desc")
GET/requests/search

client.requests.searchPage

One page of a search: a single request that reads for about 2 seconds and says how far it got.

searchPage(filters?: SearchFilters, options?: { cursor?: string }): Promise<SearchPage>
 
interface SearchPage {
  requests: SearchResult[]; // the matches this page found
  complete: boolean; // whether the whole range was read
  searchedUntil: number | null; // how far the search read (Unix ms)
  cursor: string | null; // pass to the next call; null when complete
}

A page can be short or empty without being the end: read on while complete is false.

const filters = { slug: "abc123", q: "invoice.paid", from: Date.now() - 7 * 86_400_000 };
let page = await client.requests.searchPage(filters);
while (!page.complete && page.cursor) {
  page = await client.requests.searchPage(filters, { cursor: page.cursor });
}

Pass the same filters with each cursor. A page holds at most 200 matches, offset applies to the first page only (the cursor carries what is left of it), and a cursor is opaque: pass it back as given. Give from and to as timestamps when you continue, since a duration is counted back from each call's own clock.

A cursor the server did not issue for this search (a changed one, or one from a search in the other order) throws a WebhooksCCError whose code is "invalid_cursor". A page asked for while the account's other searches are still running throws a RateLimitError with code "search_busy" and retryAfter; search() and count() wait that out themselves while it fits in their 25 seconds.

GET/requests/count

client.requests.count

Count captured requests matching the given filters. Without q and method the count is exact. With either, the server counts a long history in stretches: count() adds them up until the count is exact or 25 seconds have passed, and returns the sum, which is then a lower bound. countPage() says which.

count(filters?: SearchFilters): Promise<number>
GET/requests/count

client.requests.countPage

One count, and whether it is exact. Takes the filters of search (without limit, offset and order) and the same cursor option.

countPage(filters?: SearchFilters, options?: { cursor?: string }): Promise<SearchCountPage>
 
interface SearchCountPage {
  count: number; // matches counted by this call
  exact: boolean; // whether the whole range was counted
  searchedUntil: number | null; // how far the count read (Unix ms)
  cursor: string | null; // pass to the next call; null when exact
}

When exact is false, count covers the requests back to searchedUntil only. Calling again with cursor and the same filters counts the next stretch, so add the counts up.

DELETE/endpoints/:slug/requests

client.requests.clear

Delete captured requests for an endpoint without deleting the endpoint itself.

clear(slug: string, options?: ClearRequestsOptions): Promise<void>
ParamTypeRequiredDescription
slugstringyesEndpoint slug
beforestring | numbernoDelete requests before this duration/timestamp
GET/endpoints/:slug/requests/export

client.requests.export

Export captured requests as HAR 1.2 or cURL commands. Emails are skipped: they have no HTTP request to export.

export(slug: string, options: ExportRequestsOptions): Promise<RequestsExport>
ParamTypeRequiredDescription
slugstringyesEndpoint slug
format"har" | "curl"yesExport format
limitnumbernoMax requests to export
sincenumbernoOnly export requests after this timestamp

Provider Detection

Use detectWebhookInfo when you want the provider plus an event/topic label, or the is*Webhook helpers when you only need a boolean branch.

import { detectWebhookInfo, detectWebhookProvider, isTypeformWebhook } from "@webhooks-cc/sdk";
 
const info = detectWebhookInfo(request);
console.log(info?.provider, info?.event);
// "typeform", "form_response"
 
console.log(detectWebhookProvider(request));
// "typeform"
 
if (isTypeformWebhook(request)) {
  // Handle Typeform-specific fields
}

detectWebhookInfo returns:

type DetectedWebhookInfo = {
  provider:
    | "stripe"
    | "github"
    | "shopify"
    | "twilio"
    | "slack"
    | "paddle"
    | "linear"
    | "sendgrid"
    | "clerk"
    | "discord"
    | "vercel"
    | "gitlab"
    | "typeform"
    | "standard-webhooks"
    | "meta"
    | "lemonsqueezy"
    | "coinbase-commerce"
    | "razorpay"
    | "cal"
    | "intercom"
    | "telegram"
    | "square"
    | "hubspot"
    | "mailgun"
    | "calendly"
    | "mux"
    | "sentry"
    | "bitbucket"
    | "docusign"
    | "adyen"
    | "paypal"
    | "plaid"
    | "resend"
    | "workos";
  event: string | null;
  via: "header" | "body";
  matchedOn?: string;
};

Body Parsing

import { parseJsonBody, parseFormBody, parseBody, extractJsonField } from "@webhooks-cc/sdk";
 
// Parse JSON body safely (returns undefined on failure)
const json = parseJsonBody(request);
 
// Parse form-encoded body
const form = parseFormBody(request);
 
// Auto-detect and parse by content-type
const parsed = parseBody(request);
 
// Extract nested JSON field by dot notation
const email = extractJsonField<string>(request, "data.customer.email");

Payload Schemas

Generate types from captured requests: TypeScript interfaces, Zod schemas, Pydantic models, or JSON Schema. One schema is learned from every sample, so pass several requests of the same event to find optional fields (missing from some samples) and nullable ones (sometimes null).

import { generateRequestSchema, generatePayloadSchema } from "@webhooks-cc/sdk";
 
const requests = await client.requests.list("acme-stripe", { limit: 20 });
const { code, samples, skipped } = generateRequestSchema(requests, {
  format: "zod", // "typescript" (default), "zod", "pydantic", or "json-schema"
  name: "InvoicePaidEvent",
});
 
// From parsed values instead of requests
const ts = generatePayloadSchema([{ id: "evt_1", amount: 100 }], { name: "Payment" });

generateRequestSchema() reads JSON bodies, and form bodies as string fields; it skips emails and other bodies and counts them in skipped. payloadSample(request) returns the value it would use. Both run without network access, and @webhooks-cc/sdk/schema exports them without the client, for browser bundles.

Request Diffing

import { diffRequests } from "@webhooks-cc/sdk";
 
const diff = diffRequests(requestA, requestB);
console.log(diff.matches); // boolean
console.log(diff.differences); // { method?, path?, headers?, body? }