Skip to main content

Documentation Index

Fetch the complete documentation index at: https://supahooks.ar27111994.dev/llms.txt

Use this file to discover all available pages before exploring further.

ANY /webhook/:id is the primary ingest endpoint. It accepts any standard HTTP method and records the full request envelope — headers, query parameters, body, response, timing, and IP — for later inspection and replay.

​
Path parameters

​
id
string
required
The active webhook identifier, for example wh_abc123. The identifier must correspond to a webhook that exists and has not expired. Returns 404 if the webhook is unknown or 403 if the source IP is not in the configured allowlist.

​
Query parameters

​
__status
number
Override the HTTP response status code for this specific request. Must be a valid HTTP status integer. When the effective status is >= 400 and the response body is still the default success body, the server returns structured JSON instead of the plain success body.

​
Authentication

ANY /webhook/:id is public when authKey is not configured. When authKey is set, this endpoint uses the same auth validation as management routes — every inbound request must carry a valid Authorization: Bearer header or ?key= query parameter.

​
Default response

Without a __status override or custom script, the endpoint responds using the values configured in defaultResponseCode, defaultResponseBody, and defaultResponseHeaders: 
HTTP/1.1 200 OK
Content-Type: text/plain

OK

​
Error status override behavior

When you override the status to >= 400 and the body is still the default success body, the server replaces it with structured JSON: 
curl "https://<run-id>.runs.apify.net/webhook/wh_abc123?__status=503"

​
Example: POST a webhook payload

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"event":"payment.success","amount":9999}' \
  https://<run-id>.runs.apify.net/webhook/wh_abc123

​
Operational notes

The endpoint applies the following processing steps in order on each inbound request:
  • Webhook validation — confirms the webhook exists and has not expired.
  • IP allowlisting — if allowedIps is configured, rejects requests from addresses outside the list with 403.
  • Auth validation — enforces authKey when configured.
  • Per-webhook rate limiting — checks the per-webhook limiter before body parsing. Returns 429 when the limit is exceeded.
  • Body parsing and size enforcement — streams large payloads to Apify KVS when they exceed the offload threshold; rejects payloads above maxPayloadSize with 413.
  • JSON parsing — optionally parses JSON bodies into structured objects for search when enableJSONParsing is enabled.
  • JSON Schema validation — rejects payloads that do not match the configured jsonSchema with 400.
  • Signature verification — validates provider-specific signatures (Stripe, Shopify, GitHub, Slack, or custom) when signatureVerification is configured.
  • Custom script execution — runs customScript in a disposable worker isolate with access to event, a safe copy of req, console, and HTTP_STATUS. Script failures are logged; the capture pipeline continues through the normal response path.
  • Forwarding — forwards the request to forwardUrl if configured. Blocks self-referential forwarding loops and returns 422 when recursion is detected.
  • Response delay — if responseDelayMs is configured, the route waits artificially after processing is measured. Stored processingTime values exclude this simulated delay.
processingTime in stored log entries reflects server-side processing cost only. Any configured responseDelayMs latency simulation is applied after measurement and is not included in that value.