> ## 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.

# Input configuration reference for Webhook Debugger

> Reference for every input option in Webhook Debugger & Logger: endpoint setup, security, response mocking, forwarding, payload validation, and alerting.

Every input option you pass to Webhook Debugger & Logger controls a specific aspect of how the actor captures, secures, transforms, or responds to incoming webhook traffic. This page documents all available fields drawn from the actor's input schema, organized by functional group. You can set these values in the Apify Console input tab, pass them as JSON via the `INPUT` environment variable, or supply them through the Apify API.

<AccordionGroup>
  <Accordion title="Endpoint setup" defaultOpen={true}>
    Configure how many webhook URLs are generated and how long they stay active.

    <ParamField body="urlCount" type="integer" default="3">
      Number of unique webhook endpoints to generate for this run. Accepts a value between `1` and `50`. Each endpoint gets its own ID and captures traffic independently.
    </ParamField>

    <ParamField body="retentionHours" type="integer" default="24">
      How long generated webhook URLs remain active, in hours. Accepts `1` to `168` (one week). After expiry, the endpoint immediately stops accepting traffic and its logs are removed from `/logs` during the next cleanup cycle (up to 10 minutes later).

      <Note>
        Reducing `retentionHours` via hot-reload only affects newly generated webhooks. Pre-existing webhooks keep their original expiry window. Events already written to the Apify Dataset are not affected.
      </Note>
    </ParamField>
  </Accordion>

  <Accordion title="Traffic and payload controls">
    Protect the actor from traffic spikes and control how incoming payloads are handled.

    <ParamField body="maxPayloadSize" type="integer" default="10485760">
      Maximum allowed size for an incoming request body, in bytes. Accepts `1024` to `104857600` (100 MB). Requests that exceed this limit are rejected with `413 Request Entity Too Large`. The default is 10 MB (`10485760`).
    </ParamField>

    <ParamField body="enableJSONParsing" type="boolean" default="true">
      When enabled, the actor automatically parses `application/json` request bodies into structured dataset objects, making payload fields searchable and filterable through the `/logs` API.
    </ParamField>

    <ParamField body="rateLimitPerMinute" type="integer" default="60">
      Maximum requests per minute allowed on management endpoints (`/logs`, `/info`, `/replay`, and similar routes). The limit is applied per client IP. Accepts `1` to `1000`.
    </ParamField>
  </Accordion>

  <Accordion title="Security">
    Control who can send traffic to your endpoints and how sensitive data is handled.

    <ParamField body="maskSensitiveData" type="boolean" default="true">
      When enabled, the actor automatically redacts `Authorization`, `Cookie`, and `Set-Cookie` headers from stored logs. Enable this when you are capturing traffic from real providers to avoid persisting credentials.
    </ParamField>

    <ParamField body="redactBodyPaths" type="array">
      A list of dot-notation paths inside the JSON body to redact before storage. All paths must start with `body.` — for example, `body.token`, `body.user.password`, or `body.payment.card`. Redacted values are replaced with a placeholder in the stored event.
    </ParamField>

    <ParamField body="authKey" type="string">
      A global API key that protects all incoming requests. Senders must provide the key via an `Authorization: Bearer <key>` header or a `?key=<key>` query parameter. Treat this value as a secret.
    </ParamField>

    <ParamField body="allowedIps" type="array">
      An IP or CIDR allowlist. When set, the actor only accepts traffic from the listed addresses or blocks. Leave empty for unrestricted public access. Example entries: `203.0.113.0/24`, `198.51.100.1`.
    </ParamField>

    <ParamField body="signatureVerification" type="object">
      Configures automatic signature verification for a specific webhook provider. Set the shared secret in `signatureVerificationSecret`. Supported providers are `stripe`, `shopify`, `github`, `slack`, and `custom`.

      | Field          | Type    | Description                                                                                                           |
      | -------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
      | `provider`     | string  | Webhook provider: `stripe`, `shopify`, `github`, `slack`, or `custom`.                                                |
      | `headerName`   | string  | (Custom only) The request header that carries the signature.                                                          |
      | `timestampKey` | string  | (Custom only) The header containing the request timestamp for replay protection.                                      |
      | `algorithm`    | string  | (Custom only) HMAC algorithm: `sha256` or `sha1`. Defaults to `sha256`.                                               |
      | `encoding`     | string  | (Custom only) Signature encoding: `hex` or `base64`. Defaults to `hex`.                                               |
      | `tolerance`    | integer | Maximum age of the request timestamp in seconds before rejecting as a replay. Accepts `60`–`3600`. Defaults to `300`. |
    </ParamField>

    <ParamField body="signatureVerificationSecret" type="string">
      The signing secret used by the provider configured in `signatureVerification`. Treat this value as a secret — it is stored encrypted and never surfaced in logs.
    </ParamField>
  </Accordion>

  <Accordion title="Response mocking">
    Control the HTTP response the actor sends back to the webhook sender.

    <ParamField body="defaultResponseCode" type="integer" default="200">
      The HTTP status code returned to the sender for every captured request. Accepts any valid status code from `100` to `599`. You can override this per-request using the `__status` query parameter on the webhook URL.
    </ParamField>

    <ParamField body="defaultResponseBody" type="string">
      The exact response body returned to the sender. Supports JSON, XML, or plain text. Example: `{"status": "received", "success": true}`.
    </ParamField>

    <ParamField body="defaultResponseHeaders" type="object">
      A key-value map of HTTP headers to include in every webhook response. Example: `{"X-Custom": "Value", "Content-Type": "application/json"}`.
    </ParamField>

    <ParamField body="responseDelayMs" type="integer" default="0">
      Artificial response latency in milliseconds added after the actor finishes processing. Accepts `0` to `10000`. Use this to simulate slow or overloaded downstream systems. This delay is not included in the `processingTime` field on captured events.
    </ParamField>
  </Accordion>

  <Accordion title="Forwarding and replay">
    Configure automatic forwarding of captured requests and control retry behavior for forwarding and replay operations.

    <ParamField body="forwardUrl" type="string">
      When set, the actor automatically POSTs a copy of every captured request to this destination URL immediately after capture. Use this to pipe test traffic into a staging system while keeping a full audit trail.
    </ParamField>

    <ParamField body="forwardHeaders" type="boolean" default="true">
      When enabled, the original request headers are forwarded to `forwardUrl` along with the body. Disable this to send a clean request with only `Content-Type` and `Content-Length`.
    </ParamField>

    <ParamField body="maxForwardRetries" type="integer" default="3">
      Maximum number of retry attempts for a failed forward delivery. Accepts `0` to `10`. Retries use exponential backoff and circuit breaker protection.
    </ParamField>

    <ParamField body="replayMaxRetries" type="integer" default="3">
      Maximum number of retry attempts when replaying a stored event to a target URL. Accepts `0` to `10`.
    </ParamField>

    <ParamField body="replayTimeoutMs" type="integer" default="10000">
      Timeout per replay attempt in milliseconds. Accepts `1000` to `60000`. Keeps a slow or unresponsive target from blocking the replay pipeline.
    </ParamField>
  </Accordion>

  <Accordion title="Payload validation">
    Validate incoming payloads and run inline transformations before storage.

    <ParamField body="jsonSchema" type="string">
      A JSON Schema document (as a string) used to validate every incoming payload. Requests that do not match the schema are rejected with `400 Bad Request`. Leave empty to accept any payload structure.

      ```json theme={null}
      {
        "type": "object",
        "required": ["event"],
        "properties": {
          "event": { "type": "string" }
        }
      }
      ```
    </ParamField>

    <ParamField body="customScript" type="string">
      An inline JavaScript snippet that runs against each captured event before it is stored. Use it to normalize, enrich, or redact payload data. See [Transform webhook payloads with custom JavaScript](/configuration/custom-scripts) for full details, the script context, and usage examples.
    </ParamField>
  </Accordion>

  <Accordion title="Alerting">
    Send real-time notifications to Slack or Discord when webhook events need attention.

    <ParamField body="alerts.slack.webhookUrl" type="string">
      A Slack incoming webhook URL. When set, the actor posts alert messages to the configured Slack channel for any trigger condition listed in `alertOn`.
    </ParamField>

    <ParamField body="alerts.discord.webhookUrl" type="string">
      A Discord webhook URL. When set, the actor posts alert messages to the configured Discord channel for any trigger condition listed in `alertOn`.
    </ParamField>

    <ParamField body="alertOn" type="array" default="[&#x22;error&#x22;, &#x22;5xx&#x22;]">
      A list of conditions that trigger an alert notification. Supported values:

      | Value               | When it fires                                                                   |
      | ------------------- | ------------------------------------------------------------------------------- |
      | `error`             | An unhandled server-side error occurs during capture or processing.             |
      | `4xx`               | The actor returns a 4xx response to the sender (e.g. auth failure, rate limit). |
      | `5xx`               | The actor returns a 5xx response to the sender.                                 |
      | `timeout`           | A forward or replay request times out.                                          |
      | `signature_invalid` | Signature verification fails for an incoming request.                           |
    </ParamField>
  </Accordion>
</AccordionGroup>

<Tip>
  You can apply most of these settings at runtime without restarting the actor. On Apify, the hot-reload manager polls for updated input automatically. Locally, it watches the `storage/key_value_stores/default/INPUT.json` file. Set `DISABLE_HOT_RELOAD=true` if you want a fixed configuration.
</Tip>