> ## 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 a Partner-Signed Delivery

> Use this endpoint to deliver a payload to a workflow whose webhook trigger carries an `auth` HMAC block. The partner signs each delivery with the workflow's own secret. The route reads no bearer token. The signature is checked against the signature template of the trigger that runs, and the default is the HMAC v1 template. A single-tenant deployment serves `/v1/signed-webhooks/{path}` with no tenant segment. A signed trigger is never reachable from `/v1/webhooks` or the hub route, which answer 404 `FLK-0361`. A trigger without `auth` is never reachable here. Every refusal answers 401 with the same body, so an unknown tenant, an unknown path, a workflow without a secret, a wrong signature and a stale timestamp look the same. The run's `inputData._webhook.origin` is `signed`. A raw `Idempotency-Key` header is ignored, because the signature does not cover it. Admission by the trigger's `keyFields` identifies the delivery. Without a configured credential key the route answers 404.



## OpenAPI

````yaml /en/openapi/v3-current/flowker.yaml post /v1/signed-webhooks/{tenantId}/{path}
openapi: 3.1.0
info:
  description: >-
    Complete API reference for Flowker workflow orchestration services including
    catalog management, workflow definitions, provider configurations, and
    workflow executions.
  title: Flowker API
  version: 1.7.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: 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: 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.
  - name: Settings API
    description: >-
      Read and set per-client settings, such as how long Flowker keeps finished
      executions.
paths:
  /v1/signed-webhooks/{tenantId}/{path}:
    post:
      tags:
        - Webhooks API
      summary: Trigger a Webhook from a Partner-Signed Delivery
      description: >-
        Use this endpoint to deliver a payload to a workflow whose webhook
        trigger carries an `auth` HMAC block. The partner signs each delivery
        with the workflow's own secret. The route reads no bearer token. The
        signature is checked against the signature template of the trigger that
        runs, and the default is the HMAC v1 template. A single-tenant
        deployment serves `/v1/signed-webhooks/{path}` with no tenant segment. A
        signed trigger is never reachable from `/v1/webhooks` or the hub route,
        which answer 404 `FLK-0361`. A trigger without `auth` is never reachable
        here. Every refusal answers 401 with the same body, so an unknown
        tenant, an unknown path, a workflow without a secret, a wrong signature
        and a stale timestamp look the same. The run's
        `inputData._webhook.origin` is `signed`. A raw `Idempotency-Key` header
        is ignored, because the signature does not cover it. Admission by the
        trigger's `keyFields` identifies the delivery. Without a configured
        credential key the route answers 404.
      operationId: triggerSignedWebhook
      parameters:
        - description: >-
            Tenant the workflow belongs to. Multi-tenant deployments only.
            Single-tenant deployments omit this segment.
          in: path
          name: tenantId
          required: true
          schema:
            type: string
        - description: Webhook path registered by the workflow trigger.
          in: path
          name: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              description: >-
                Free-form webhook payload, validated at runtime against the
                route's input contract.
              type: object
        description: >-
          The delivered payload, byte for byte. The signature covers the bytes,
          so do not re-encode them in transit.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionResultsOutput'
          description: >-
            Indicates that a synchronous workflow finished within the wait
            window.
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionCreateOutput'
          description: >-
            Indicates that Flowker accepted the delivery, or that a synchronous
            run is parked at a wait.
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: >-
            Indicates that the delivery was not proven to come from the partner.
            The answer is the same for every cause.
        '413':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Indicates that the body is larger than the 1 MB limit.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionResultsOutput'
          description: Indicates that a synchronous run failed.
        '503':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: >-
            Indicates that the credential store or the tenant database is
            temporarily unavailable. Retry.
        '504':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionCreateOutput'
          description: >-
            Indicates that a synchronous run was still running when the wait
            window closed. The body is the receipt.
      security: []
components:
  schemas:
    ExecutionResultsOutput:
      example:
        executionId: f7e6d5c4-b3a2-1098-7654-321fedcba098
        workflowId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        status: completed
        stepResults:
          - stepNumber: 1
            stepName: Set Payment Output
            nodeId: set-output
            status: completed
            output:
              actionType: set_output
              output:
                status: received
            executedAt: '2026-03-17T14:35:00Z'
            durationMs: 0
        finalOutput:
          status: 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: true
          description: Aggregated output from the last step or the workflow's final result.
          example:
            status: 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
        definitionDigest:
          description: Digest of the workflow definition that the run used.
          type: string
        operationKey:
          description: >-
            Identity of the operation that the run admits, built from the
            `admission.keyFields` of the workflow. Absent without admission.
          type: string
        operationReplayed:
          description: True when the answer replays the first run of the same operation.
          type: boolean
      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: Status of the execution.
          example: running
          type: string
        workflowId:
          description: ID of the workflow being executed.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          format: uuid
          type: string
        definitionDigest:
          description: Digest of the workflow definition that the run used.
          type: string
        operationKey:
          description: >-
            Identity of the operation that the run admits, built from the
            `admission.keyFields` of the workflow. Absent without admission.
          type: string
        operationReplayed:
          description: True when the answer replays the first run of the same operation.
          type: boolean
        testRun:
          description: >-
            True for a test run: reads run for real, writes stop, and the record
            expires 24 hours after it started.
          example: true
          type: boolean
      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
    StepResultOutput:
      properties:
        attempts:
          description: >-
            Number of calls Flowker sent to the network for this step. `0` when
            Flowker sent no call.
          example: 1
          type: integer
        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
        errorClass:
          description: >-
            Category of the failure: `client_error`, `auth_error`, `transient`,
            `circuit_open`, or `timeout`. Present only on a failed step.
          example: client_error
          type: string
        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: set-output
          type: string
        output:
          additionalProperties:
            type: object
          description: Output data produced by this step.
          example:
            actionType: set_output
            output:
              status: received
          type: object
        rawBody:
          description: >-
            The provider answer as received, up to its first 8 KiB. Present when
            `bodyFormat` or `bodyParseError` is set.
          example: <Ack><Status>OK</Status></Ack>
          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
        retried:
          description: Whether Flowker sent more than one network call for this step.
          example: false
          type: boolean
        status:
          description: 'Status of this step: `completed` or `failed`.'
          example: completed
          type: string
        statusCode:
          description: >-
            HTTP status the provider returned. Absent when no HTTP response
            arrived.
          example: 422
          type: integer
        stepName:
          description: Human-readable name of the step.
          example: Set Payment Output
          type: string
        stepNumber:
          description: Position of this step in the execution sequence (1-indexed).
          example: 1
          type: integer
        activation:
          description: >-
            The step's stable identity: the node ID, then @scope inside a loop
            pass. A repeat scope is loopId#pass (one-based), a foreach scope is
            loopId:"key" with the item key quoted; nested loops join with /.
            Omitted for a step recorded before loops existed.
          example: node-validate@loop-1:"CTR-9"
          type: string
        effectOutcome:
          description: >-
            What is known about an effect write: response (the provider
            answered, any status), not_sent (proven not to have left) or unknown
            (it may have reached the provider). Omitted while the write is
            awaiting its answer and for nodes without an effect block.
          enum:
            - response
            - not_sent
            - unknown
          example: unknown
          type: string
        effectReason:
          description: >-
            Why the effect was not_sent (refused_before_send, body_too_large,
            auth, connect, circuit_open, deadline) or unknown (timeout,
            disconnect, read, lease_expired).
          enum:
            - refused_before_send
            - body_too_large
            - auth
            - connect
            - circuit_open
            - deadline
            - timeout
            - disconnect
            - read
            - lease_expired
          example: timeout
          type: string
        requestDigest:
          description: >-
            sha256 of the body prepared to send, hex. Present for an effect
            write; omitted for a node with private_inputs.
          example: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
          type: string
        simulated:
          description: >-
            True when a test run answered this step without the real call: a
            wait that passed at once.
          type: boolean
        wouldSend:
          $ref: '#/components/schemas/StepRequest'
          description: >-
            The request a test run stopped before sending, with secrets masked.
            Omitted when the request could not be built (private input, file
            request, S3 call).
      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
    StepRequest:
      additionalProperties: false
      properties:
        body:
          type: string
        headers:
          additionalProperties:
            type: string
          type: object
        method:
          type: string
        url:
          type: string
      required:
        - method
        - url
        - headers
        - body
      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 <token>`.

````

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