Webhooks — API & CLI

Everything about the Webhook node that involves a terminal: the ingress endpoint and its status codes, the headers it reads, the REST routes that manage webhooks and events, and the hostwh CLI. What the node is and how to set it up from the dashboard is on the Webhook node page; this one is its reference.

The ingress endpoint

One route, one verb. POST /api/in/:token, where the token is the Webhook ID from the screen. It is public — no session, no bearer token unless the webhook has Require API key on — and it does not answer GET, PUT, PATCH or HEAD.

curl -X POST https://api.hostwebhook.com/api/in/<webhook-id> \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4821-created" \
  -d '{ "type": "order.created", "id": "evt_4821" }'

curl -X POST https://api.hostwebhook.com/api/in/<webhook-id> \
  -H "Authorization: Bearer hwk_..." \
  -H "Content-Type: application/json" \
  -d '{ "type": "order.created", "id": "evt_4821" }'

The key must belong to the same organization as the webhook, be on the webhook's list of allowed keys, and carry ingress:write (or the older, wider events:write). See API keys.

Any content type is accepted and the raw body is kept; JSON is parsed when it parses. The JSON body limit is 10 MB. Multipart uploads are handled separately, capped at 10 files, 25 parts, 20 fields, 1 MB per field and 200 MB in total, with the per-file size coming from your plan — a multipart field named payload or data is parsed as the payload, and uploaded files arrive as _files.

What it answers

Where the delivery id is read from

In this order. The first one found wins; if none is found the delivery has no identity and is never treated as a duplicate.

1. An explicit header — Idempotency-Key or X-Idempotency-Key.
2. A provider's delivery id — X-GitHub-Delivery, X-Shopify-Event-Id, webhook-id (the Standard Webhooks header), PAYPAL-TRANSMISSION-ID or I-Twilio-Idempotency-Token.
3. An id in the body — top-level id, event.id, MessageSid or CallSid.

The window is enforced in Redis and clamped to your plan's ceiling at delivery time — 300 s on free, 3600 s on pro, 86400 s on enterprise. Saving a value above the ceiling is refused with a 403.

Signature headers, by type

A body that fails verification is not silently dropped: an event is written with status SIGNATURE_INVALID so you can see it in the events list, and the caller gets a 401. The full rules for each type — what to sign, the 300-second replay window, working examples in Node and Postman, and how to reference a Signing Secret instead of pasting one — are in Incoming signature verification. The outgoing side — how HostWebhook signs what it delivers to your server — is on the Signing page.

Managing webhooks over the API

Everything under /api/webhooks is authenticated, by bearer token or by the session cookie, and scoped: webhooks:read to read, webhooks:write to change.

curl -X POST https://api.hostwebhook.com/api/webhooks \
  -H "Authorization: Bearer hwk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "<your-workspace-id>",
    "name": "Stripe production",
    "targetUrl": "https://api.myapp.com/webhooks/stripe",
    "maxRetries": 5,
    "retryDelaySeconds": 60,
    "retryStrategy": "exponential-capped",
    "incomingSignatureType": "stripe",
    "incomingSignatureSecret": "whsec_...",
    "ingressRateLimitPerMinute": 600,
    "responseMode": "none",
    "priority": 0,
    "fallbackUrls": ["https://api-eu.myapp.com/webhooks/stripe"]
  }'

The field names of the configuration form, for the API:

Events, retries and the DLQ

Deliveries run through a BullMQ queue. The backoff is the one you chose: a fixed retryDelaySeconds for linear, or that value doubled on each attempt for the two exponential strategies, capped at 30 minutes by default.

The dead-letter queue is not a separate queue — it is the events that reached FAILED, carrying dlqEnteredAt, dlqExpiresAt and dlqAcknowledged. That is why Auto-Replay DLQ on Recovery in the config form can simply replay the unacknowledged ones once the target comes back.

These routes take events:read to look and events:write to act. Note that ingress:write — the scope for a key you hand to a sender — opens none of them.

Flow links

The flow-link rows in the node's Internal calls list are documents of their own, at /api/flow-links — POST, GET, GET /:id, PATCH /:id and DELETE /:id, with canvas:read to read and canvas:write to change. A link carries its source (sourceWorkspaceId, sourceNodeType, sourceNodeId), its target, and three switches: sync — on by default, the caller waits for the target pipeline — timeoutMs (30 000 by default — lowered to your plan's ceiling when that is lower; an explicit value above the ceiling is a 403) and enabled. The list can be filtered by sourceNodeType + sourceNodeId or targetNodeType + targetNodeId, and its rows carry the name of each end.

curl -X POST https://api.hostwebhook.com/api/flow-links \
  -H "Authorization: Bearer hwk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "<your-workspace-id>",
    "sourceWorkspaceId": "<workspace A>",
    "sourceNodeType": "webhook",
    "sourceNodeId": "<W_A>",
    "targetWorkspaceId": "<workspace B>",
    "targetNodeType": "webhook",
    "targetNodeId": "<W_B>",
    "sync": true
  }'

An internal call does not go through the ingress: the link (or the AI Node's tool call) writes the event straight into the target webhook — for a link with eventType: "flow-link" and the headers x-hw-flow-link (the link's id) and x-hw-call-stack; for a tool call with eventType: "ai-tool" and x-hw-ai-tool — and a _meta envelope on the payload:

{
  "_meta": {
    "iterable": false,
    "count": 1,
    "source": "flow-link",          // or "ai-tool"
    "sourceNodeType": "webhook",    // or "ai"
    "sourceNodeId": "66f1…"
  },
  "…the payload the source received or produced…": "…"
}

That envelope is on the stored event, not in front of your nodes: the flow receives the payload without _meta, so {{payload._meta.source}} resolves to nothing in a template. Nor does $() cross: the target flow sees its own workspace's nodes by name, and only the payload carries anything over from the source. Both flows do share one run — the synthetic event keeps the source's correlationId.

dispatchCount and lastDispatchedAt move only when the target webhook actually ran — a link skipped because the target is paused or one side has Internal calls off does not count, and a sync link whose wait ran out does, because the target ran anyway. Deleting a webhook or an AI Node deletes the links it is the source or the target of. The full behaviour — the relay to the target's own links, its Target URL, loops, depth and where a skipped link is reported — is on the Webhook node page.

CLI

The CLI is hostwh. Its reason to exist, for this node, is local development: a webhook's target URL cannot point at localhost — the API rejects private addresses — so the CLI holds the connection open and pushes deliveries down it instead. The walkthrough is on Local development.

npm install -g hostwh
hostwh login

login opens a browser by default; pass -p, --password for the email-and-password prompt instead. Credentials land in ~/.hostwh/config.json.

Forwarding to a local port

Two shapes, depending on whether you want the webhook to outlive the session.

hostwh forward http://localhost:3001/webhooks

Creates a temporary webhook, prints its ingress URL, forwards everything that arrives to the local URL, and deletes the webhook on Ctrl+C. Add --show-payload or --show-headers to print what came through.

hostwh create --name "stripe-dev" --url https://myapp.com/webhooks
hostwh endpoints
hostwh listen <webhook-id> --forward http://localhost:3001/webhooks --show-payload

hostwh listen <id> without --forward only streams events to your terminal, which is the cheapest way to see whether a provider is reaching you at all. With --forward it becomes a tunnel and POSTs each delivery to the local URL, allowing 29 seconds for your handler to answer.

The commands that concern this node

Ids are shown as their last 8 characters, and every command that takes an id accepts either those 8 or the full value. The API host comes from HOSTWEBHOOK_API_URL (default https://api.hostwebhook.com), and --api-url on login persists it.