> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zenrows.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The Zenrows HTTP API serves Fetch and Extract (extract=auto) at https://api.zenrows.com/v1/, Crawl at https://api.zenrows.com/v1/crawls, and Batch at https://async.api.zenrows.com/v1. Fetch, Extract, Crawl and Batch are described in OpenAPI 3.1 at https://www.zenrows.com/openapi.json and listed in the RFC 9727 API catalog at https://www.zenrows.com/.well-known/api-catalog. Every endpoint also has its own page under /api-reference with its schema. Use the spec for exact parameter names and types. Crawl's endpoints, parameters and errors are also at https://docs.zenrows.com/crawl/endpoints.md. To call Zenrows from an agent, connect the MCP server at https://mcp.zenrows.com/mcp. To search these docs from an agent, connect the docs MCP server at https://docs.zenrows.com/mcp. Agent skills for Zenrows are published at https://github.com/ZenRows/cli and install with `npx skills add ZenRows/cli`.

# Send a synthetic test event to a webhook URL

> Synchronous one-shot dispatch of a `webhook.test` event
against a caller-supplied URL. Independent of any job: body
carries the same `{ url, signature }` shape as the submit-time
webhook field. Used by integrators to verify a receiver is
reachable, terminates TLS, and validates the signature before
attaching the URL to a real job.

Validation is identical to submit (HTTPS, 1-second DNS lookup,
active HMAC key required when `signature: true`). On validation
failure, returns the same Problem JSON codes
(`callback_url_must_be_https`, `callback_url_unresolvable`,
`webhook_signing_requires_active_key`).

On validation pass, always returns `200 OK`; the receiver
outcome rides in the body so callers can distinguish
"the API rejected my config" (4xx) from "my receiver
returned 500" (200 + `delivered: false`).




## OpenAPI

````yaml /api-reference/openapi.json post /webhook/test
openapi: 3.1.0
info:
  title: Zenrows API
  version: 1.0.0
  summary: >-
    Reach any page, including the protected web, and return it as HTML,
    Markdown, plaintext, PDF or structured JSON.
  description: >-
    Zenrows is web data infrastructure for agents and applications. Three HTTP
    surfaces are described here:


    - **Fetch and Extract**: one synchronous request per page, at
    `https://api.zenrows.com/v1/`. Authentication is the `apikey` query
    parameter.

    - **Crawl**: collect the URLs behind one start page, at
    `https://api.zenrows.com/v1/crawls`. Authentication is the `X-API-Key`
    header or the `apikey` query parameter.

    - **Batch**: asynchronous jobs of up to 100,000 URLs, at
    `https://async.api.zenrows.com/v1`. Authentication is the `X-API-Key`
    header.


    **Browser** is not described here because it is not HTTP: you connect
    Puppeteer or Playwright to a WebSocket endpoint. See
    https://docs.zenrows.com/browser-sessions/introduction.


    **Cost.** A request costs 1 credit, 5 with JavaScript rendering, 10 with
    premium proxies, 25 with both, and 1 to 25 under `mode=auto`. Failed
    requests are not charged, except target `404` and `410` answers, which are
    billed like a success. The free tier is 5,000 credits a month, no card.


    **Versioning and deprecation.** The version is in the URL path (`/v1`, the
    only version so far). Inside a version Zenrows only adds: new endpoints,
    optional parameters, response fields and headers. Nothing is removed or
    changed. Retiring a version is announced at least twelve months ahead, and
    every response from a deprecated version carries the `Deprecation` (RFC
    9745) and `Sunset` (RFC 8594) headers. Policy:
    https://docs.zenrows.com/api-versioning.


    **Getting a key without a human.** `POST
    https://app.zenrows.com/api/agent/signup` returns a usable key; the spec is
    at https://www.zenrows.com/auth.md and a setup playbook at
    https://www.zenrows.com/SKILL.md.
  termsOfService: https://www.zenrows.com/legal/terms-of-use
  contact:
    name: Zenrows support
    email: support@zenrows.com
    url: https://www.zenrows.com/contact
  license:
    name: Proprietary
    url: https://www.zenrows.com/legal/terms-of-use
servers:
  - url: https://api.zenrows.com/v1
    description: Fetch and Extract (synchronous)
security:
  - apiKeyQuery: []
tags:
  - name: Fetch
    description: Retrieve one page, optionally rendered, proxied, converted or extracted.
  - name: Extract
    description: Which domains Extract serves, and getting a new one prepared.
  - name: Crawl
    description: Collect the URLs behind one start page, and each page's HTML when asked.
  - name: Batch
    description: Submit many URLs as one job and collect the results.
  - name: Account
    description: Plan, credits and concurrency for the calling key.
  - name: Onboarding
    description: Get a working key with no human in the loop.
externalDocs:
  description: Zenrows documentation
  url: https://docs.zenrows.com
paths:
  /webhook/test:
    post:
      tags:
        - Batch
      summary: Send a synthetic test event to a webhook URL
      description: |
        Synchronous one-shot dispatch of a `webhook.test` event
        against a caller-supplied URL. Independent of any job: body
        carries the same `{ url, signature }` shape as the submit-time
        webhook field. Used by integrators to verify a receiver is
        reachable, terminates TLS, and validates the signature before
        attaching the URL to a real job.

        Validation is identical to submit (HTTPS, 1-second DNS lookup,
        active HMAC key required when `signature: true`). On validation
        failure, returns the same Problem JSON codes
        (`callback_url_must_be_https`, `callback_url_unresolvable`,
        `webhook_signing_requires_active_key`).

        On validation pass, always returns `200 OK`; the receiver
        outcome rides in the body so callers can distinguish
        "the API rejected my config" (4xx) from "my receiver
        returned 500" (200 + `delivered: false`).
      operationId: testWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchTestWebhookRequest'
      responses:
        '200':
          description: |
            Dispatch attempted. Inspect `delivered` to see whether the
            receiver returned 2xx.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchTestWebhookResponse'
        '400':
          description: |
            Validation failed: HTTPS / DNS / missing active HMAC key.
            The receiver was not contacted.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BatchProblem'
        '401':
          $ref: '#/components/responses/BatchUnauthenticated'
        '403':
          $ref: '#/components/responses/BatchForbidden'
        '503':
          $ref: '#/components/responses/BatchUnavailable'
      security:
        - apiKeyHeader: []
      servers:
        - url: https://async.api.zenrows.com/v1
          description: Batch (asynchronous jobs)
components:
  schemas:
    BatchTestWebhookRequest:
      type: object
      required:
        - url
      description: |
        Body for `POST /v1/webhook/test`. Same shape as the submit-time
        `webhook` field; `signature` is optional and defaults `false`.
      properties:
        url:
          type: string
          format: uri
          description: |
            HTTPS only. Host must resolve via DNS within 1 second.
            Identical validation to the submit/PUT webhook URL.
        signature:
          type: boolean
          default: false
          description: |
            When `true`, the test event is signed with the account's
            active HMAC key: same `X-Signature: t,v1,kid` header
            real deliveries use. Returns `400
            webhook_signing_requires_active_key` when no active key
            exists.
    BatchTestWebhookResponse:
      type: object
      required:
        - delivered
        - event_id
        - elapsed_ms
      description: |
        Outcome of the synthetic test dispatch. HTTP status is always
        `200` when the request was validated: the receiver outcome
        is in the body. The synthetic envelope uses `event_type:
        "webhook.test"` and stable sentinel IDs (`job_id`/`run_id` =
        `"test"`) so receivers can recognise and discard test traffic.
      properties:
        delivered:
          type: boolean
          description: |
            `true` iff the receiver responded with a 2xx status. `false`
            on non-2xx, timeout, or transport error.
        event_id:
          type: string
          description: |
            ID of the synthetic event. Different on every call so
            receivers' dedup tables don't suppress repeated tests.
        status_code:
          type: integer
          description: |
            HTTP status returned by the receiver. Absent on timeout or
            transport error (no response was received).
        error:
          type: string
          description: |
            Human-readable reason when `delivered: false`. Same
            vocabulary as real webhook deliveries
            (`http_4xx:<code>`, `http_5xx:<code>`, `timeout`,
            `transport_error:<detail>`). Absent on success.
        elapsed_ms:
          type: integer
          description: Wall-clock duration of the receiver POST in milliseconds.
    BatchProblem:
      type: object
      description: |
        RFC 7807 Problem Details.
      required:
        - type
        - title
        - status
        - code
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        code:
          type: string
          description: >
            Stable machine-readable error code. Branch on this, not on

            `detail` or `title`. `type` links to the code's entry in the

            public error reference. Codes and their usual status:


            | Status | Codes |

            |---|---|

            | 400 | `invalid_argument` (with `invalid_tasks` for per-task
            problems), `callback_url_must_be_https`,
            `callback_url_unresolvable`, `webhook_signing_requires_active_key` |

            | 401 | `unauthenticated`, `subscription_inactive` (a verified,
            enabled account whose subscription is past due, unpaid, incomplete
            or paused; `detail` stays "Subscription is not active.") |

            | 402 | `payment_required`, `api_key_cap_reached` |

            | 403 | `permission_denied` (the Batch API is not enabled for this
            account) |

            | 404 | `not_found` (job, run, task or export),
            `file_input_not_found` |

            | 409 | `conflict`, `job_not_open`, `last_batch_received`,
            `run_not_terminal`, `run_not_stoppable`, `no_prior_run`,
            `no_matching_tasks`, `run_has_descendants`,
            `idempotency_key_conflict`, `task_not_ready`,
            `partial_rerun_window_expired`, `candidate_pending`, `no_candidate`,
            `file_input_not_uploaded`, `file_input_unsupported_for_job_type` |

            | 410 | `result_expired` (a task's content past the result window,
            or an export past `expires_at`) |

            | 429 | `quota_exceeded` |

            | 500 / 503 | `internal` |


            A failed task's stored `error` uses the scraping engine's

            own codes, plus `gateway_unreachable` (503),

            `gateway_timeout` (504), `gateway_bad_response` and

            `internal` (500) for attempts that failed before the engine

            answered with Problem JSON.


            A path that matches no API route answers a plain `404`

            without a Problem body.


            Clients must accept values not listed here.
        instance:
          type: string
          description: Always `/v1`; it does not name the request path.
        invalid_tasks:
          type: array
          description: Present on validation errors.
          items:
            type: object
            required:
              - index
              - reason
            properties:
              index:
                type: integer
              reason:
                type: string
                x-extensible-enum: true
                description: Clients must accept values not listed here.
                enum:
                  - malformed_url
                  - unsupported_scheme
                  - missing_host
                  - url_too_long
                  - metadata_too_large
                  - metadata_key_invalid
                  - invalid_external_id
                  - unknown_param
                  - invalid_param_value
                  - unsupported_method
                  - body_not_allowed
                  - body_too_large
                  - body_malformed
                  - method_param_conflict
              value:
                type: string
                description: |
                  Offending input. For URL / metadata reasons this is
                  a redacted/truncated form of the bad value. For
                  `unknown_param` / `invalid_param_value` this is the
                  param key.
      additionalProperties: true
  responses:
    BatchUnauthenticated:
      description: Missing / invalid API key.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BatchProblem'
    BatchForbidden:
      description: |
        `permission_denied`: the Batch API is not enabled for this
        account. Any `/v1` route can return it.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BatchProblem'
    BatchUnavailable:
      description: Transient upstream failure; safe to retry.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BatchProblem'
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: apikey
      description: >-
        Fetch, Extract, Crawl and the account endpoint accept the key as the
        `apikey` query parameter. Keys are per account and self-serve: create
        one in the Zenrows dashboard (app.zenrows.com), or, for an agent with no
        human present, `POST https://app.zenrows.com/api/agent/signup`.
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Batch, Crawl, the Extract endpoints and the account endpoint read the
        same key from the `X-API-Key` header.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.