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

# Trigger a Workflow Webhook

> Start a workflow with client tracking metadata and enforce required metadata fields.

Use the URL shown on the published Webhook Trigger node. The trigger's configured authentication mode applies. Raydocs API token mode requires `workflows-execute` and an administrator token owner for the workflow workspace.

## Attach run metadata

Include an optional reserved `_raydocs` object in the request body. Its only supported field is `metadata`. Raydocs stores these values on the run and removes `_raydocs` before passing the other fields to the workflow.

```json theme={null}
{
  "document_url": "https://example.com/invoice.pdf",
  "_raydocs": {
    "metadata": {
      "client_id": "CLI-0042",
      "client_name": "Étude Dupont",
      "external_request_id": "REQ-789"
    }
  }
}
```

Metadata is a flat JSON object of strings: at most 20 keys, 500 characters per value and 8 KiB total when serialized without whitespace. Keys start with an ASCII letter and contain up to 64 ASCII letters, digits, underscores or hyphens. Nested values, arrays, numbers, booleans, nulls and null bytes are rejected. String values are preserved, including leading zeroes and spaces.

A top-level business field named `metadata` remains ordinary workflow input. Only `_raydocs.metadata` attaches run metadata. In multipart requests, send `_raydocs` as a JSON string field alongside the uploaded files.

## Require fields on a trigger

Configure metadata keys, labels and required flags in the Webhook Trigger node, then publish the workflow version. Each trigger has its own rules. Extra metadata keys remain accepted within the global limits. With no required fields configured, metadata is optional.

A required value must be present and contain a non-whitespace string. Validation runs after authentication and before run creation, file storage or job dispatch. A rejected request returns 422 and creates no run:

```json theme={null}
{
  "message": "The given data was invalid.",
  "errors": {
    "_raydocs.metadata.client_id": ["This metadata field is required."]
  }
}
```

## Trace the caller

Raydocs stores the authenticated token ID, its name at creation, and its owner's user ID. Other authentication modes record the mode but do not identify a Raydocs user. Metadata is supplied by the integration; requiring `client_id` checks presence, not membership in a client registry.

Accepted calls return 202 with `id`, `status` and `trigger_node_id`. Use the run ID to read the run or its public output. Metadata remains fixed for that execution and is inherited by subworkflows. Replays retain business metadata and record the new caller.


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