Super.ai Webhook Data API

openapi: 3.2.0
info:
  title: SuperAI Flow Platform Webhook Data API
  description: SuperAI Flows is a workflow orchestration platform that enables you to design, deploy, and monitor automated workflows at scale.
  version: 0.1.0
tags:
- name: webhook-data
  description: Push data from external systems to a flow execution's waiting 'Wait for Webhook' task. A 2xx acknowledgment means the data is durably stored; identical redeliveries are idempotent.
  x-displayName: Webhook Data
paths:
  /api/flow-executions/{flow_execution_id}/webhook-data:
    post:
      tags:
      - webhook-data
      summary: Submit webhook data for a waiting task
      description: 'Push data to a flow execution''s waiting "Wait for Webhook" task.


        The flow pauses when it reaches a webhook receiver task and resumes with

        the submitted `data` as the task''s output. Data may also be submitted

        before the flow reaches the task; it is stored and picked up when the task

        runs.


        Delivery contract:

        - A 2xx response means the data is durably stored and will not be lost.

        - Retrying with the identical body is safe and idempotent (returns

        status ''duplicate'').

        - Retry on 5xx. Do not retry 4xx unchanged: 422 means the data does not

        match the task''s schema; 409 with different data means the first

        delivery already won.


        Context:

        - The target task is addressed by `task_name` in the request body; a

        flow may contain multiple webhook receiver tasks.

        - Authenticate with an organization API key (X-API-Key) or a user JWT.'
      operationId: receive_webhook_data_api_flow_executions__flow_execution_id__webhook_data_post
      parameters:
      - name: flow_execution_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Flow Execution Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookDataCreateRequest'
      responses:
        '200':
          description: Webhook data durably stored ('received') or already stored ('duplicate')
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDataAckResponse'
        '400':
          description: Bad Request - The named task is not a webhook receiver task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Caller's role may not submit webhook data (org admins and users only)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Flow execution not found, or no task with this name in its flow definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict - The flow execution already finished, or different data was already stored for this task (first write wins)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Data does not match the task's output model - fix the payload, do not retry as-is
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid authentication credentials
          content:
            application/json:
              examples:
                missing_token:
                  summary: Missing authentication token
                  value:
                    error:
                      message: Authentication required
                      code: unauthorized
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    error:
                      message: Invalid authentication token
                      code: unauthorized
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error:
                      message: Internal server error
                      code: internal_error
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                repository_error:
                  summary: Database error
                  value:
                    error:
                      message: Database operation failed
                      code: repository_error
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
      - APIKeyAuth: []
components:
  schemas:
    ErrorDetail:
      properties:
        message:
          type: string
          title: Message
          description: Human-readable error message
        code:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
          description: Machine-readable error code for programmatic handling
        details:
          anyOf:
          - items:
              type: string
            type: array
          - items:
              additionalProperties: true
              type: object
            type: array
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Details
          description: Additional error context, validation errors, or debugging information
      type: object
      required:
      - message
      title: ErrorDetail
      description: 'Standard error detail structure.


        This model matches the error format returned by the centralized

        exception handlers in app/api/errors/handlers.py.'
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Request Id
          description: 'Unique request identifier in ULID format for debugging and support. Example: 01K8KABR6S16YETA2SZPVBS9SP'
      type: object
      required:
      - error
      title: ErrorResponse
      description: "Standard API error response structure.\n\nAll error responses from the API follow this format, ensuring\nconsistent error handling for API consumers.\n\nExample:\n    {\n        \"error\": {\n            \"message\": \"Flow not found\",\n            \"code\": \"not_found\"\n        },\n        \"request_id\": \"01K8KABR6S16YETA2SZPVBS9SP\"\n    }"
      examples:
      - error:
          code: not_found
          message: Resource not found
        request_id: 01K8KABR6S16YETA2SZPVBS9SP
    WebhookDataCreateRequest:
      properties:
        task_name:
          type: string
          title: Task Name
          description: Name of the webhook_receiver task in the flow that waits for this data.
          examples:
          - wait_for_validation
        data:
          additionalProperties: true
          type: object
          title: Data
          description: The data for the task. Must match the task's output model (defined by its fields parameter); unknown fields or type mismatches are rejected with 422. Note that field values are compared exactly for duplicate detection — re-sending the identical body is acknowledged idempotently, while a different body for the same task is rejected with 409.
      type: object
      required:
      - task_name
      - data
      title: WebhookDataCreateRequest
      description: Payload submitted by an external system for a waiting webhook_receiver task.
    WebhookDataAckResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Identifier of the stored payload row.
        status:
          type: string
          enum:
          - received
          - duplicate
          title: Status
          description: '''received'' on first delivery, ''duplicate'' when the identical payload was already stored.'
      type: object
      required:
      - id
      - status
      title: WebhookDataAckResponse
      description: Acknowledgment that a webhook payload is durably stored.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT Bearer token authentication. Include your access token in the Authorization header as: `Bearer YOUR_ACCESS_TOKEN`


        Example:

        ```

        Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

        ```'
    APIKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
      description: 'API key authentication. Include your API key in the X-API-Key header as: `X-API-Key YOUR_API_KEY`


        Example:

        ```

        X-API-Key: saf_1234567890

        ```'