Skip to content

API Reference: Forwarding

TypeScript SDK reference for forwarding: destinations, filters, formats, secrets, deliveries, alerts and templates.

Updated Nov 2026

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

Forwarding

Forwarding sends what an endpoint captures to up to 10 destinations, each with its own kinds, conditions, format, timing and signing secret, queued, retried and logged. client.forwarding manages the endpoint's primary destination (the one its forwardUrl stands for) and reads the delivery log of all of them; client.destinations manages each one. Only the endpoint's owner can manage forwarding: for anyone else these methods throw NotFoundError, and configure() fails with a 403 for team members. In your handler, verify relayed requests with verifyRelayedRequest(), signed JSON and your own JSON with verifyForwardedRequest() or verifyForwardedEmail().

await client.forwarding.configure(slug, {
  url: "https://api.example.com/hooks",
  http: true,
  headers: [{ name: "Authorization", value: `Bearer ${process.env.HOOK_TOKEN}` }],
  sentField: "publishedAt",
});
const secret = await client.forwarding.secret(slug); // put it in your handler
 
const result = await client.forwarding.test(slug, { kind: "http" });
if (result.delivered) {
  await client.forwarding.configure(slug, { enabled: true });
}
PATCH/endpoints/:slug

client.forwarding.configure

Change the primary destination's settings and return the updated endpoint. Only the options you pass change. Saving the first URL creates the endpoint's signing secret, so you can send a test delivery before turning forwarding on. Turning forwarding, or one kind of it, off marks the deliveries still waiting as failed. Throws when no option is given.

configure(endpointSlug: string, options: ConfigureForwardingOptions): Promise<Endpoint>
ParamTypeRequiredDescription
endpointSlugstringyesEndpoint slug
urlstring | nullnoAn https URL on a public host name, or null to remove it (forwarding must be off)
enabledbooleannoTurn forwarding on or off. Turning it on needs a URL, sent now or saved before
httpbooleannoForward HTTP requests
emailbooleannoForward emails
format"auto" | "as_received" | "json" | "chat"noHow deliveries go out; "auto" picks chat for Slack and Discord URLs and as received otherwise. See Formats
headers{ name: string; value: string | null }[]noYour own headers, at most 10, for relayed and signed JSON deliveries. Replaces the whole list; null keeps the value stored under that name
appendPathbooleannoAdd the path after the slug to the URL for relayed requests (default true)
retrySeconds0 | 3600 | 86400noRetry failed deliveries for a day (default), an hour, or not at all
keepOrderbooleannoOne delivery at a time, in capture order (default false)
sentFieldstring | nullnoA JSON body field with the sender's own timestamp, such as "publishedAt" or "data.publishedAt". See Timing
GET/endpoints/:slug/forwarding

client.forwarding.secret

The endpoint's signing secret (whsec_...). Throws NotFoundError until a URL has been saved.

secret(endpointSlug: string): Promise<string>
POST/endpoints/:slug/forwarding

client.forwarding.rotateSecret

Replace the signing secret and return the new one. Every delivery from then on, retries included, is signed with it, so update your handler right away.

rotateSecret(endpointSlug: string): Promise<string>
POST/endpoints/:slug/forwarding/test

client.forwarding.test

Send the newest captured request of a kind (or a sample, when none has arrived) to the saved URL once, exactly as a delivery would go out, and report the answer. kind defaults to "http" when HTTP requests are forwarded, otherwise "email". Works with forwarding on or off; nothing is retried or logged. Fails with a 400 when no URL is saved. Rate limited to 10 per minute.

test(endpointSlug: string, options?: { kind?: "http" | "email" }): Promise<ForwardingTestResult>
// Returns: { status, durationMs, excerpt, error, delivered, sample, kind, format, url, target, request, sender }
GET/endpoints/:slug/deliveries

client.forwarding.deliveries

The endpoint's delivery log, newest first. Each row has its destination ({ id, name, url }), the status, your server's last answer and time, the format, the request's method and path (or an email's subject), when it was received, and senderAt when the request carried the sender's own timestamp.

deliveries(endpointSlug: string, options?: ListDeliveriesOptions): Promise<DeliveryLogEntry[]>
ParamTypeRequiredDescription
endpointSlugstringyesEndpoint slug
limitnumberno1 to 100 (default: 5)
status"all" | "pending" | "failed" | "skipped"no"pending" is queued or retrying, "skipped" filtered out (default: all)
destinationIdstringnoOnly this destination's deliveries
beforestringnoA row's cursor, to list the rows after it
GET/endpoints/:slug/deliveries/summary

client.forwarding.summary

Delivered and failed among the last 24 hours, waiting now, and the failed and total counts the log's filters show. Each count stops at 100,000. With destinationId, the counts are that destination's alone, matching deliveries() with the same option.

summary(endpointSlug: string, options?: { destinationId?: string }): Promise<DeliverySummary>
// Returns: { last24h: { delivered, failed }, pending, failed, total }
GET/requests/:id/deliveries

client.forwarding.requestDeliveries

Every delivery of one captured request or email, with each try in attemptLog. Anyone who can read the request can call this; team members get the destination's host without its path. emailDeliveries() is the older name for the same call.

requestDeliveries(requestId: string): Promise<ForwardingDelivery[]>
POST/requests/:id/deliveries

client.forwarding.redeliver

Queue a request or email for delivery again with the current settings, to every destination that takes it, and return the new delivery's id. It also sends one that was never forwarded. With destinationId, it goes to that destination only, whatever its filter says (the dashboard's Send anyway). Fails with a 409 when no destination takes it. Rate limited to 30 per minute.

redeliver(requestId: string, options?: { destinationId?: string }): Promise<{ id: string }>
POST/endpoints/:slug/deliveries/redeliver-failed

client.forwarding.redeliverFailed

Queue every request whose latest delivery failed again, oldest first, with each destination's current settings; with destinationId, only that destination's. At most 1,000 deliveries wait for a destination at a time, so queued can be lower than the failed count; call it again once those are through. Fails with a 409 when no destination is on. Rate limited to 10 per minute.

redeliverFailed(endpointSlug: string, options?: { destinationId?: string }): Promise<{ queued: number }>

Destinations

Each destination of an endpoint decides what it gets (http, email, a filter), how it is sent (format: "as_received", "json", "template" with your bodyTemplate, or "chat" with an optional messageTemplate, "sheets" rows in a Google Sheet, or "file_drop" files on your own server) and when (throttleSeconds, delaySeconds). See Forwarding for what each does.

const zap = await client.destinations.create(slug, {
  url: "https://hooks.zapier.com/hooks/catch/123/abc",
  email: false,
  filter: { conditions: [{ field: "body_path", op: "eq", path: "type", value: "invoice.paid" }] },
  format: "template",
  bodyTemplate: {
    invoice: "{{ json.data.object.id }}",
    amount: "{{ json.data.object.amount_paid }}",
  },
});
const preview = await client.destinations.preview(slug, { destinationId: zap.id });
// preview.filterPasses, preview.delivery?.body
GET/endpoints/:slug/destinations

client.destinations.list

The endpoint's destinations in order, header values masked. With summary: true, each has summary: its last 24 hours (delivered, failed, skipped) and what is waiting.

list(endpointSlug: string, options?: { summary?: boolean }): Promise<Destination[]>
get(endpointSlug: string, destinationId: string): Promise<Destination>
POST/endpoints/:slug/destinations

client.destinations.create

Add a destination, up to 10 per endpoint. It is on unless enabled: false, and gets a signing secret of its own. Templates and filters are checked before the request is sent, so a mistake throws with the field it is in.

create(endpointSlug: string, input: DestinationCreateInput): Promise<Destination>
// DestinationCreateInput: DestinationInput with a url, or a file drop's format and config
ParamTypeRequiredDescription
urlstringyesAn https URL on a public host name, or a Slack or Discord webhook (not for a file drop)
namestring | nullnoFor the list and the log
enabledbooleannoSend to it (default true)
http, emailbooleannoWhich kinds it takes (default both)
filter{ logic?: "and" | "or"; conditions: Condition[] } | nullnoSend only matching captures. See Send only some captures
formatDestinationFormatnoDefault "auto": chat for Slack and Discord URLs, as received otherwise. Also "as_received", "json", "template", "chat", "sheets" (Google Sheets), "file_drop" (File drops, Business), and for emails a mail provider's shape: "postmark", "sendgrid", "mailgun", "cloudmailin"
mailgunSigningKeystring | nullnoWith "mailgun": your Mailgun signing key, so signature verifies (write-only; hasMailgunSigningKey says one is saved)
bodyTemplateJSONnoWith "template": the body; its strings hold {{ placeholders }} (Your own JSON)
messageTemplatestring | nullnoWith "chat": your own message text; null sends the standard message
headers{ name: string; value: string | null }[]noYour own headers, at most 10 (not for chat). Replaces the list; null keeps a stored value
appendPathbooleannoAdd the captured path to the URL for relayed requests (default true)
retrySeconds0 | 3600 | 86400noRetry failed deliveries for a day (default), an hour, or not at all
keepOrderbooleannoOne delivery at a time, in capture order
sentFieldstring | nullnoA JSON body field with the sender's own timestamp
throttleSecondsnumbernoAt most one delivery every so many seconds (0 to 3,600); the rest are not sent
delaySecondsnumbernoWait this long after the capture before sending (0 to 3,600)
attachments"links" | "inline" | "none"noHow a stored email's attachments travel: signed links (default), inline base64, or names only
configSheetsConfig | FileDropConfig | nullnoWith "sheets": the spreadsheet, tab and columns; with "file_drop": the server, folder and file layout
dropSecret{ password?, privateKey?, secretAccessKey? } | nullnoWith "file_drop": the login secret, write-only, needed again when the server or login changes
positionnumbernoIts place in the list
PATCH/endpoints/:slug/destinations/:id

client.destinations.update

Change a destination; only the fields you pass change. Switching it off or taking a kind away marks what is waiting for it as failed.

update(endpointSlug: string, destinationId: string, input: DestinationInput): Promise<Destination>
DELETE/endpoints/:slug/destinations/:id

client.destinations.delete

Remove a destination. Deliveries still waiting for it are marked failed; its log stays.

delete(endpointSlug: string, destinationId: string): Promise<void>
PUT/endpoints/:slug/destinations/order

client.destinations.reorder

Put the destinations in this order (every id, once) and return them. Captures are queued for destinations in this order.

reorder(endpointSlug: string, destinationIds: string[]): Promise<Destination[]>
GET/endpoints/:slug/destinations/:id/secret

client.destinations.secret

The destination's signing secret (whsec_...); rotateSecret() replaces it and returns the new one, used by every delivery from then on.

secret(endpointSlug: string, destinationId: string): Promise<string>
rotateSecret(endpointSlug: string, destinationId: string): Promise<string>
POST/endpoints/:slug/destinations/:id/test

client.destinations.test

Send one delivery now, exactly as a real one would go out: requestId, or the newest request of kind, or a sample. Its filter is reported in filterPasses, not applied; nothing is retried or logged. Rate limited to 10 per minute.

test(
  endpointSlug: string,
  destinationId: string,
  options?: { kind?: "http" | "email"; requestId?: string }
): Promise<DestinationTestResult>
// Returns what forwarding.test() does, plus filterPasses
POST/endpoints/:slug/destinations/preview

client.destinations.preview

A dry run against a captured request: whether the destination takes its kind (takesKind), whether its filter lets it through (filterPasses), and the exact request it would send (delivery: method, URL, headers with stored values masked, body), or an error such as a template that cannot be filled in. Pass a saved destinationId, unsaved fields in destination (on top of the saved ones, or with a url on their own), or both. Nothing is sent.

preview(endpointSlug: string, options: PreviewDestinationOptions): Promise<DestinationPreview>

Alerts

GET/endpoints/:slug/alerts

client.alerts

An endpoint's alerts: when its email fields stop finding values, mail stops arriving, or a delivery fails for good. get() returns the settings and the recent alerts, open (resolvedAt: null) or resolved; update() changes only the settings you pass and returns them.

get(slug: string): Promise<{ settings: AlertSettings; events: AlertEvent[] }>
update(slug: string, settings: Partial<AlertSettings>): Promise<AlertSettings>
// AlertSettings: { enabled, fieldFailures, fieldFailureShare, requiredFields, silenceHours,
//                  destinationFailures, notifyEmail, notifyDestinationIds }
await client.alerts.update(slug, { enabled: true, silenceHours: 24, notifyEmail: true });

Templates

GET(local)

client.templates.listProviders

List all supported webhook provider templates. No API call made.

listProviders(): TemplateProvider[]
// Returns: ["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"]
GET(local)

client.templates.get

Get metadata for a specific provider template.

get(provider: TemplateProvider): TemplateProviderInfo