> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Trigger a Webhook (PUT) > Receives a webhook callback via HTTP PUT and triggers the associated workflow execution. The path is dynamically resolved against the webhook registry — each workflow can register its own webhook path. The runtime accepts GET, POST, PUT, PATCH, and DELETE on this route, as well as nested paths with multiple segments. ## OpenAPI ````yaml en/openapi/v3-current/flowker.yaml put /v1/webhooks/{path} openapi: 3.1.0 info: description: >- Complete API reference for Flowker workflow orchestration services including catalog management, workflow definitions, executor configurations, provider configurations, and workflow executions. title: Flowker API version: 1.2.0 servers: - url: https://flowker.sandbox.lerian.net security: - BearerAuth: [] tags: - name: Catalog API description: >- Browse built-in providers, executors, and triggers available in the Flowker catalog. - name: Workflows API description: >- Create, update, activate, deactivate, clone, and delete workflow definitions. - name: Executions API description: Start workflow executions and track their status and results. - name: Executor Configurations API description: >- List, inspect, update, and delete the executor configuration records a deployment holds. - name: Provider Configurations API description: >- Create, update, enable, and disable the provider configurations that workflow nodes call through. - name: Dashboard API description: >- Retrieve aggregated summaries of workflows and executions for operational dashboards. - name: Webhooks API description: >- Receive webhook callbacks from external systems to trigger workflow executions. - name: Schedule API description: >- Inspect a workflow's upcoming, skipped, and parked scheduled occurrences, and run or discard the parked ones. - name: Schema Registry API description: >- Publish global OpenAPI specification versions for native services and pin the version each tenant resolves against. - name: OpenAPI Schemas API description: >- Upload, inspect, and delete the tenant's external OpenAPI schemas, and derive the contract of a single operation. - name: XSD Schemas API description: >- Upload, inspect, and delete the tenant's XSD schemas used to validate XML webhook payloads. paths: /v1/webhooks/{path}: put: tags: - Webhooks API summary: Trigger a Webhook (PUT) description: >- Receives a webhook callback via HTTP PUT and triggers the associated workflow execution. The path is dynamically resolved against the webhook registry — each workflow can register its own webhook path. The runtime accepts GET, POST, PUT, PATCH, and DELETE on this route, as well as nested paths with multiple segments. operationId: triggerWebhookPut parameters: - description: >- Webhook path registered by a workflow. Supports nested paths with multiple segments at runtime. Forward slashes within the path must be percent-encoded as `%2F` per RFC 3986/OpenAPI 3.1 (for example, use `orders%2Fpaid` for `orders/paid`). in: path name: path required: true schema: type: string - description: >- Optional idempotency key to prevent duplicate executions from the same webhook delivery. in: header name: Idempotency-Key schema: type: string requestBody: content: application/json: schema: type: object additionalProperties: true description: >- Webhook payload from the external system. Flowker injects webhook metadata (`_webhook` key with method, path, headers, query params, and remote IP) before passing to the workflow. application/xml: schema: type: object additionalProperties: true description: >- Webhook payload from the external system, encoded as XML when the trigger runs an XSD or OpenAPI XML contract. description: Webhook payload. Maximum size is 1 MB. required: false responses: '200': content: application/json: schema: $ref: '#/components/schemas/ExecutionResultsOutput' application/xml: schema: $ref: '#/components/schemas/ExecutionResultsOutput' description: >- The workflow finished inside the synchronous window. The body carries the final business results. An XML route returns the equivalent `` document. '202': content: application/json: schema: $ref: '#/components/schemas/ExecutionCreateOutput' application/xml: schema: $ref: '#/components/schemas/ExecutionCreateOutput' description: >- Execution accepted. The body carries the receipt for an asynchronous run, or for a synchronous run that exceeded its wait window. An XML route returns the equivalent `` document. '400': content: application/json: schema: $ref: '#/components/schemas/WebhookErrorResponse' description: Indicates that the request body is malformed or could not be parsed. '401': content: application/json: schema: $ref: '#/components/schemas/WebhookErrorResponse' description: >- Unauthorized. The request carries no valid Bearer token, or the caller lacks the `execute` permission on the `webhooks` resource. '404': content: application/json: schema: $ref: '#/components/schemas/WebhookErrorResponse' description: >- No webhook registered for this path and HTTP method, or the associated workflow was not found. '409': content: application/json: schema: $ref: '#/components/schemas/WebhookErrorResponse' description: >- Duplicate idempotency key — this webhook delivery was already processed. '413': content: application/json: schema: $ref: '#/components/schemas/WebhookErrorResponse' description: Webhook payload exceeds the 1 MB size limit. '422': content: application/json: schema: $ref: '#/components/schemas/WebhookErrorResponse' description: >- The associated workflow is not in an active state and cannot be executed. '500': content: application/json: schema: $ref: '#/components/schemas/WebhookErrorResponse' description: >- Indicates an unexpected internal error. If this persists, please contact support. components: schemas: ExecutionResultsOutput: example: executionId: f7e6d5c4-b3a2-1098-7654-321fedcba098 workflowId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 status: completed stepResults: - stepNumber: 1 stepName: action_log-event nodeId: log-event status: completed output: action: log executedAt: '2026-03-17T14:35:00Z' durationMs: 0 finalOutput: workflow: transactionId: txn-98765 amount: 1500 currency: BRL customerId: cust-12345 message: Payment received startedAt: '2026-03-17T14:35:00Z' completedAt: '2026-03-17T14:35:00Z' properties: completedAt: description: Timestamp when the execution finished. example: '2026-03-17T14:35:12Z' format: date-time type: string executionId: description: Unique identifier of the execution. example: f7e6d5c4-b3a2-1098-7654-321fedcba098 format: uuid type: string finalOutput: additionalProperties: type: object description: Aggregated output from the last step or the workflow's final result. example: workflow: transactionId: txn-98765 amount: 1500 currency: BRL customerId: cust-12345 message: Payment received type: object startedAt: description: Timestamp when the execution started. example: '2026-03-17T14:35:00Z' format: date-time type: string status: description: Final status of the execution. example: completed type: string stepResults: description: Ordered list of results for each step executed. items: $ref: '#/components/schemas/StepResultOutput' type: array workflowId: description: ID of the workflow that was executed. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 format: uuid type: string type: object ExecutionCreateOutput: properties: executionId: description: Unique identifier of the execution. example: f7e6d5c4-b3a2-1098-7654-321fedcba098 format: uuid type: string startedAt: description: Timestamp when the execution started. example: '2026-03-17T14:35:00Z' format: date-time type: string status: description: Initial status of the execution (always `pending`). example: running type: string workflowId: description: ID of the workflow being executed. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 format: uuid type: string type: object WebhookErrorResponse: description: Error body returned by a JSON webhook route. properties: code: description: Stable, machine-readable Flowker error code. example: FLK-0361 type: string message: description: Human-readable explanation of this occurrence. example: no webhook registered for this path and method type: string title: description: Standard HTTP reason phrase for the response status. example: Not Found type: string type: object StepResultOutput: properties: durationMs: description: Time taken to execute this step, in milliseconds. example: 0 type: integer errorMessage: description: Error message if the step failed. Null on success. type: string executedAt: description: Timestamp when this step was executed. example: '2026-03-17T14:35:02Z' format: date-time type: string nodeId: description: ID of the workflow node that was executed. example: log-event type: string output: additionalProperties: type: object description: Output data produced by this step. example: action: log type: object status: description: 'Status of this step: `completed`, `failed`, or `skipped`.' example: completed type: string stepName: description: Human-readable name of the step. example: action_log-event type: string stepNumber: description: Position of this step in the execution sequence (1-indexed). example: 1 type: integer type: object securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT bearer token issued by the identity provider. Send it in the Authorization header as `Bearer `. ````