> ## Documentation Index > Fetch the complete documentation index at: https://docs.anyformat.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Webhook > Subscribe an HTTPS endpoint to run events *Rate limit tier: **general**, 600 requests/min. See [Rate limits](https://docs.anyformat.ai/api-reference-v3/introduction.md#rate-limits).* Subscribes an HTTPS endpoint to the [events](https://docs.anyformat.ai/api-reference-v3/webhooks/overview.md#events) you name. `events` is required and takes at least one event. The response carries the webhook's `secret`, the key that [verifies each delivery](https://docs.anyformat.ai/api-reference-v3/webhooks/overview.md#verifying-a-delivery). Store it: no other response returns it. The URL must use HTTPS and resolve to a public address. A URL that resolves to a private or reserved address answers `400 INVALID_VALUE`, and one whose hostname does not resolve answers `422 URL_UNREACHABLE`. An organization that already holds 50 webhooks answers `409 WEBHOOK_SUBSCRIPTION_LIMIT`. Send a [ping](https://docs.anyformat.ai/api-reference-v3/webhooks/ping.md) to check the endpoint before a run ends. ```bash curl theme={null} curl -X POST 'https://api.anyformat.ai/v3/webhooks/' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"url": "https://example.com/webhooks/anyformat", "events": ["run.completed", "run.failed"]}' ``` ## OpenAPI ````yaml POST /v3/webhooks/ openapi: 3.1.0 info: title: anyformat API description: > Document extraction and workflow automation API. AnyFormat lets you define extraction workflows that pull structured data from any document — PDFs, images, scanned files, or plain text. Upload a file, run it through a workflow, and get back structured fields with confidence scores and source evidence. ## Quick start See the [Quick start guide](https://docs.anyformat.ai/api-reference-v3/introduction) for a walkthrough. ## Authentication All endpoints (except `/health/`) require a Bearer token in the `Authorization` header: ``` Authorization: Bearer ``` Get your API key from [app.anyformat.ai/api-key](https://app.anyformat.ai/api-key). ## Versioning Endpoints are versioned by path prefix (`/v3/`). Every response under a versioned prefix includes `X-API-Version`. version: 3.0.0 servers: - url: https://api.anyformat.ai description: API server security: [] tags: - name: workflows description: >- Workflows define extraction templates — what fields to extract from documents. Create workflows, upload files, run extractions, and fetch results. - name: document-packets description: >- Document packets group uploaded documents for a workflow. Address a packet directly to (re-)run its workflow. - name: runs description: >- Extraction runs — the first-class result entity. Each run is a single execution of a workflow against a document packet; fetch its status and results flat by run id. - name: splits description: >- Splits — the sub-documents a splitter node carves out of a packet. Download any one of them as a PDF, built from the source documents on request and never stored. - name: webhooks description: >- Webhooks — an HTTPS endpoint of yours that hears of every run's ending, signed per the Standard Webhooks specification, instead of polling the run. - name: parse description: >- Parse a single document with the platform's fast lite parse — a one-call shortcut over the workflow upload + run primitives, backed by your organization's system parse workflow. - name: health description: Health check endpoints to verify API availability. paths: /v3/webhooks/: post: tags: - webhooks summary: Create a webhook description: >- Subscribe an HTTPS endpoint to run events. Each delivery is a `POST` signed per [Standard Webhooks](https://www.standardwebhooks.com/): verify the `webhook-signature` header with the `secret` this response returns, once. An organization holds at most 50 webhooks. Only an admin or owner of the organization manages its webhooks: an API key whose owner has a lower role gets `403`. operationId: v3_create_webhook requestBody: content: application/json: schema: $ref: '#/components/schemas/WebhookCreateRequestV3' required: true responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/WebhookCreatedV3' headers: X-RateLimit-Limit: description: Requests allowed per window (60s). schema: type: integer X-RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer X-RateLimit-Reset: description: Seconds until the current window resets. schema: type: integer '400': description: >- `VALIDATION_ERROR` — The request failed validation. `detail` is a list of `{type, loc, msg}`, one per failure; `loc[0]` is the request part. `INVALID_VALUE` — A value in the request is not valid. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: VALIDATION_ERROR: value: error: The request failed validation. detail: - type: missing loc: - body - name msg: Field required error_code: VALIDATION_ERROR retryable: false request_id: req_abc123 recovery: >- Read `detail` for what failed validation, correct the request, and send it again. INVALID_VALUE: value: error: A value in the request is not valid. detail: A value in the request is not valid. error_code: INVALID_VALUE retryable: false request_id: req_abc123 recovery: >- Read `detail` for the value that was rejected, correct it, and send the request again. '401': description: >- Authentication failed — the API key is not valid (`INVALID_API_KEY`) or the request carries none (`MISSING_API_KEY`). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: INVALID_API_KEY: value: error: The API key is not valid. detail: The API key is not valid. error_code: INVALID_API_KEY retryable: false request_id: req_abc123 recovery: >- Check that the key is complete and has not been revoked, or create a new key. MISSING_API_KEY: value: error: The request carries no API key. detail: The request carries no API key. error_code: MISSING_API_KEY retryable: false request_id: req_abc123 recovery: >- Send your API key in the `Authorization: Bearer ` header. '403': description: '`ACCESS_DENIED` — You do not have access to this resource.' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: ACCESS_DENIED: value: error: You do not have access to this resource. detail: You do not have access to this resource. error_code: ACCESS_DENIED retryable: false request_id: req_abc123 recovery: >- Use an API key from the organization that owns this resource, or ask one of its admins for access. '404': description: '`NOT_FOUND` — The resource does not exist.' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: NOT_FOUND: value: error: The resource does not exist. detail: The resource does not exist. error_code: NOT_FOUND retryable: false request_id: req_abc123 recovery: >- Check the ID, and that it belongs to your API key's organization; `params.resource_type` names what is missing. '409': description: >- `WEBHOOK_SUBSCRIPTION_LIMIT` — The organization has reached its webhook subscription limit. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: WEBHOOK_SUBSCRIPTION_LIMIT: value: error: >- The organization has reached its webhook subscription limit. detail: >- The organization has reached its webhook subscription limit. error_code: WEBHOOK_SUBSCRIPTION_LIMIT retryable: false request_id: req_abc123 recovery: >- Delete a webhook the organization no longer needs, then create this one again. '422': description: '`URL_UNREACHABLE` — The URL''s hostname could not be resolved.' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: URL_UNREACHABLE: value: error: The URL's hostname could not be resolved. detail: The URL's hostname could not be resolved. error_code: URL_UNREACHABLE retryable: false request_id: req_abc123 recovery: >- Check that the URL's hostname resolves in public DNS, then send the request again. '429': description: >- Rate limited — retry after the `Retry-After` header. Default windows: 60 requests/minute for extraction submission, 600 requests/minute for general endpoints. headers: Retry-After: description: Seconds until the next request is allowed. schema: type: integer X-RateLimit-Limit: description: Requests allowed per window (60s). schema: type: integer X-RateLimit-Remaining: description: Requests remaining in the current window. schema: type: integer X-RateLimit-Reset: description: Seconds until the current window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: RATE_LIMITED: value: error: Too many requests. detail: Too many requests. error_code: RATE_LIMITED retryable: true request_id: req_abc123 recovery: >- Wait the seconds the `Retry-After` header gives, or back off exponentially without one, then retry. '500': description: >- An internal error stopped the request — `retryable=true`. Retry with backoff. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: INTERNAL_ERROR: value: error: An internal error stopped the request. detail: An internal error stopped the request. error_code: INTERNAL_ERROR retryable: true request_id: req_abc123 recovery: >- Retry with exponential backoff, and contact support with the `request_id` if it keeps failing. '502': description: >- A backend service broke the connection before it answered, or failed. Retry with backoff when `retryable` is true. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: INTERNAL_ERROR: value: error: An internal error stopped the request. detail: An internal error stopped the request. error_code: INTERNAL_ERROR retryable: true request_id: req_abc123 recovery: >- Retry with exponential backoff, and contact support with the `request_id` if it keeps failing. '503': description: >- A backend service could not be reached or is unavailable (`SERVICE_UNAVAILABLE`). Retry with backoff when `retryable` is true. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: SERVICE_UNAVAILABLE: value: error: The service is temporarily unavailable. detail: The service is temporarily unavailable. error_code: SERVICE_UNAVAILABLE retryable: true request_id: req_abc123 recovery: Retry the request with exponential backoff. '504': description: >- A backend service did not answer in time. Retry with backoff when `retryable` is true. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: GATEWAY_TIMEOUT: value: error: The upstream service did not answer in time. detail: The upstream service did not answer in time. error_code: GATEWAY_TIMEOUT retryable: true request_id: req_abc123 recovery: Retry the request with exponential backoff. security: - ApiKeyAuth: [] components: schemas: WebhookCreateRequestV3: properties: url: type: string maxLength: 2048 pattern: ^https:// title: Url description: >- The HTTPS endpoint that receives the events. It must resolve to a public address. examples: - https://example.com/webhooks/anyformat events: items: type: string enum: - run.completed - run.failed - run.cancelled type: array minItems: 1 title: Events description: >- Event types the endpoint receives. `run.completed`: a run ended `processed`. `run.failed`: a run ended `error`. `run.cancelled`: a run ended `cancelled`. examples: - - run.completed - run.failed type: object required: - url - events title: WebhookCreateRequestV3 WebhookCreatedV3: properties: id: type: string title: Id description: Unique identifier of the webhook (hyphenated UUID). examples: - 069dcc2c-e14c-7606-8000-2ee4fb17b4e3 url: type: string title: Url description: The endpoint that receives the events. examples: - https://example.com/webhooks/anyformat events: items: type: string enum: - run.completed - run.failed - run.cancelled type: array title: Events description: >- Event types the endpoint receives. `run.completed`: a run ended `processed`. `run.failed`: a run ended `error`. `run.cancelled`: a run ended `cancelled`. examples: - - run.completed - run.failed created_at: type: string format: date-time title: Created At description: Timestamp when the webhook was created (ISO 8601). secret: type: string title: Secret description: >- The signing secret, `whsec_` and base64. Verify each delivery's `webhook-signature` with it. **Only this response carries it: store it securely.** examples: - whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw type: object required: - id - url - events - created_at - secret title: WebhookCreatedV3 ErrorEnvelope: type: object title: ErrorEnvelope description: >- Uniform error response. `retryable=true` means the same request may succeed on retry (with backoff); `retryable=false` means the caller must change the request before retrying. required: - error - error_code - retryable - request_id properties: error: type: string description: Short human-readable summary. detail: description: >- Machine-readable detail, any JSON value. A string for most errors, a list of `{type, loc, msg}` objects for `VALIDATION_ERROR`, whose `loc` starts with `body`, `query`, `path`, `header`, `form` or `tool`, and an object for a structured error such as `FILENAME_CONFLICT` (`detail.conflicts`). error_code: type: string enum: - ACCESS_DENIED - AUTH_FAILED - CONCURRENT_EDIT - CONFLICT - DATASET_DOCUMENT_REJECTED - DATASET_GROUND_TRUTH_SAVE_FAILED - DATASET_INVALID_REQUEST - DATASET_UNSUPPORTED - EMPTY_EVAL - ENDPOINT_RETIRED - EXTRACT_MODE_FORBIDDEN - EXTRACT_NODE_UNRESOLVED - FILENAME_CONFLICT - FILE_TOO_LARGE - GATEWAY_TIMEOUT - GONE - GRAPH_READBACK_FAILED - GT_INVALID - IDEMPOTENCY_KEY_REUSED - IMMUTABLE_WORKFLOW - INSUFFICIENT_CREDIT - INTERNAL_ERROR - INTERNAL_INCONSISTENCY - INVALID_API_KEY - INVALID_JSON - INVALID_LOOKUP_FILE_ENCODING - INVALID_VALUE - INVALID_WORKFLOW_CONFIG - KNOWLEDGE_NOT_ENABLED - KNOWLEDGE_NOT_READY - KNOWLEDGE_THREAD_MISMATCH - KNOWLEDGE_UNSUPPORTED_SNAPSHOT_FORMAT - LOOKUP_FIELD_WITHOUT_FILE - METHOD_NOT_ALLOWED - MISSING_API_KEY - MULTIFILE_UNSUPPORTED - NOT_ACCEPTABLE - NOT_ASSIGNED_VERIFIER - NOT_FOUND - NOT_IMPLEMENTED - NOT_IN_DATASET - OBJECT_STORAGE_UNAVAILABLE - ONESHOT_SIGNALS_MISSING - OPERATOR_DEPRECATED - OPERATOR_NOT_AVAILABLE - OPTIMIZATION_ALREADY_RUNNING - PARSE_MODE_FORBIDDEN - PAYMENT_REQUIRED - PRECONDITION_FAILED - RATE_LIMITED - REPARSE_REQUIRED - REQUEST_REJECTED - REQUEST_TOO_LARGE - RUN_IN_PROGRESS - SERVICE_UNAVAILABLE - SPLIT_HAS_NO_PAGES - SPLIT_SOURCE_NOT_PDF - TOPOLOGY_INVALID - UNSUPPORTED_FILE_TYPE - UNSUPPORTED_LOOKUP_FILE - UNSUPPORTED_MEDIA_TYPE - UPLOAD_SNIFF_BUDGET_EXCEEDED - URL_UNREACHABLE - VALIDATION_ERROR - WEBHOOK_SUBSCRIPTION_LIMIT - WORKFLOW_CONCURRENT_EDIT - WORKFLOW_NAME_CONFLICT - ZERO_DATA_RETENTION_REFUSES_DATASET - ZERO_DATA_RETENTION_REFUSES_KNOWLEDGE - deprecated_operator_ack_required - insufficient_api_key_scope - terms_acceptance_required description: >- Stable identifier for programmatic handling. New values can be added at any time, so a client must accept a code it does not know. examples: - VALIDATION_ERROR - AUTH_FAILED - NOT_FOUND - PRECONDITION_FAILED - RATE_LIMITED - INTERNAL_ERROR - GATEWAY_TIMEOUT retryable: type: boolean description: True when the caller should retry (with backoff for 429/412/5xx). request_id: type: string description: Correlates this response with server logs. params: type: object additionalProperties: true description: >- Values specific to this occurrence of the error that a caller needs to recover, such as `node_ids` or `required_scope`, keyed by name. Absent when the code relays none. doc_url: type: string format: uri description: Link to the documentation of this `error_code`. recovery: type: string description: >- One sentence that says what to do next. Absent when the `error_code` has none, or when `retryable` differs from the code's usual value. securitySchemes: ApiKeyAuth: type: http description: >- API key issued from app.anyformat.ai/api-key. Send as `Authorization: Bearer `. scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.