> ## 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 from Streaming Hub > Use this endpoint as the `endpoint` of a Streaming Hub webhook subscription. It triggers the same workflow execution as `POST /v1/webhooks/{path}`. Only the authentication is different: this route takes no Bearer token. Flowker verifies an HMAC-v1 signature over the raw request body with the tenant's inbound signing secret, which the deployment keeps in its secrets backend. The signing secret of the subscription and the stored secret must be the same value. Flowker refuses a legacy `sha256=` (v0) signature, because v0 has no replay protection. Flowker serves this route only when the deployment turns on the signed Streaming Hub ingress. It is off by default. ## OpenAPI ````yaml /pt/openapi/v3-current/flowker.yaml post /v1/hub/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.4.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/hub/webhooks/{path}: post: tags: - Webhooks API summary: Trigger a Webhook from Streaming Hub description: >- Use this endpoint as the `endpoint` of a Streaming Hub webhook subscription. It triggers the same workflow execution as `POST /v1/webhooks/{path}`. Only the authentication is different: this route takes no Bearer token. Flowker verifies an HMAC-v1 signature over the raw request body with the tenant's inbound signing secret, which the deployment keeps in its secrets backend. The signing secret of the subscription and the stored secret must be the same value. Flowker refuses a legacy `sha256=` (v0) signature, because v0 has no replay protection. Flowker serves this route only when the deployment turns on the signed Streaming Hub ingress. It is off by default. operationId: triggerSignedHubWebhook 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: >- HMAC-v1 signature over the raw body, in the form `v1,sha256=`. The hex value is the HMAC-SHA256 of `v1:.`, keyed with the tenant's inbound signing secret. During a signing-secret rotation, the header repeats once for each active secret, two values at most. Flowker accepts the delivery when one value verifies. in: header name: X-Webhook-Signature required: true schema: type: string - description: >- Unix time in seconds, the same value the signature covers. Flowker rejects a timestamp outside the freshness window, five minutes by default, even when the signature is correct. in: header name: X-Webhook-Timestamp required: true schema: type: string - description: >- Tenant that owns the delivery. Flowker uses it to select the signing secret to check. A valid signature confirms it. in: header name: X-Lerian-Tenant-Id required: true schema: type: string - description: >- Streaming Hub event ID. Flowker uses it as the replay key for each workflow. A delivery that repeats an event ID returns the first execution and does not run the workflow again. in: header name: X-Lerian-Event-Id schema: type: string - description: >- Delivery-attempt ID, recorded for correlation. It changes on every retry of the same event. in: header name: X-Lerian-Delivery-Id schema: type: string - description: >- Optional idempotency key. A repeated key returns the prior execution. When the delivery carries `X-Lerian-Event-Id`, the event ID takes precedence. in: header name: Idempotency-Key schema: type: string requestBody: content: application/json: schema: type: object additionalProperties: true description: >- Event payload. When the webhook trigger defines an input contract, Flowker validates the payload against it. description: >- The delivered event, byte for byte. The signature covers these bytes, so they must not be re-encoded in transit. Maximum size is 1 MB. required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ExecutionResultsOutput' description: >- The workflow finished inside the synchronous window. The body carries the final business results. '202': content: application/json: 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. '400': content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' application/json: schema: $ref: '#/components/schemas/WebhookErrorResponse' description: >- A required delivery header is missing or malformed, the delivery carries more than two signature values, or the body could not be parsed. '401': content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Flowker could not prove that the delivery comes from Streaming Hub. The response is the same for an unknown or unprovisioned tenant, a wrong secret, a stale timestamp, and a legacy v0 signature, so it does not show which tenants exist or which part of the credential is wrong. '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. '413': content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- The delivery body exceeds the 1 MB limit. Flowker refuses it before it checks the signature. '422': content: application/json: schema: $ref: '#/components/schemas/WebhookErrorResponse' description: >- The associated workflow is not active, or the payload does not satisfy the trigger's input contract. '500': content: application/json: schema: $ref: '#/components/schemas/WebhookErrorResponse' description: >- Indicates an unexpected internal error. If this persists, please contact support. '503': content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' application/json: schema: $ref: '#/components/schemas/WebhookErrorResponse' description: >- The signing-secret store or the tenant database is temporarily unavailable, or Flowker cannot check the payload against the trigger's input contract. Flowker did not accept or reject the delivery, so a retry is safe. security: [] 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 ErrorResponse: properties: code: description: Stable, machine-readable Flowker error code. example: FLK-0001 type: string detail: description: >- Human-readable explanation of this occurrence. Responses with a status of 500 or above carry a fixed generic message. example: name is a required field type: string errors: description: Per-field entries for a request that failed validation. items: $ref: '#/components/schemas/ErrorDetail' type: array instance: description: URI reference identifying this specific occurrence. example: /v1/workflows format: uri type: string status: description: HTTP status code. example: 400 type: integer title: description: >- Standard HTTP reason phrase for the status. It does not change per error code. example: Bad Request type: string type: description: >- URI reference identifying the error. Always the error catalog base followed by the code. example: https://errors.lerian.studio/v1/FLK-0001 format: uri 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: bodyFormat: description: >- `xml` when the provider answered in XML, whether or not Flowker could decode the answer. Absent for a JSON answer. example: xml type: string bodyParseError: description: >- Reason Flowker could not decode the provider's XML answer. The step still completes, and `output` carries no body. example: 'XML syntax error on line 1: unexpected EOF' type: string 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 rawBody: description: >- The provider answer as received, up to its first 8 KiB. Present when `bodyFormat` or `bodyParseError` is set. example: OK type: string requestFormat: description: >- Request format the node configures: `json`, `xml_converted`, or `xml_passthrough`. Absent when the node configures none. example: xml_converted type: string 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 ErrorDetail: properties: location: description: Where the problem is, such as body.nodes or path.id. example: body.nodes type: string message: description: Description of the field-level problem. example: expected array length >= 1 type: string value: description: The value that caused the error, when it is safe to echo. 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 `. ````