> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useasterisk.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Document only operations in the linked OpenAPI contract: the source-data ingestion operations and the source-scoped outbound webhook management operations.
> Treat the generated OpenAPI document as authoritative for request fields. Never invent compatibility fields, alternate endpoints, or additional source models.
> Preserve explicit nulls, decimal strings, timestamps, source identifiers, immutable version identifiers, and document-version links exactly as defined.

# Get a webhook event

> Returns events recorded for the calling ingestion source, including events that no endpoint received because none was ACTIVE and subscribed when they occurred. Each item has the same fields and values as the delivered envelope, and its id matches Karsa-Webhook-Id; JSON key order can differ and items are not signed. Events are readable for the webhook history window, 30 days by default.



## OpenAPI

````yaml /openapi/ingestion.openapi.yaml get /api/ingestion/webhook-events/{eventId}
openapi: 3.1.0
info:
  title: Karsa Data Ingestion API
  version: current
  description: >-
    Source-bound writes for documents, business onboardings, customers,
    kyb-dossiers, accounts, transactions, outcomes, screening observations,
    screening dispositions, monitoring controls, monitoring control executions,
    historical RFI events, source checkpoints, native SEON screening
    observations, native AiPrise screening observations, and native Chainalysis
    screening observations.
servers:
  - url: https://api.sandbox.useasterisk.com
    description: Karsa sandbox API (synthetic test data)
  - url: https://api.useasterisk.com
    description: Karsa production API
security: []
tags:
  - name: Customers
    description: >-
      Create and version individual or business customer records, including
      atomic business onboarding where every beneficial owner is an individual
      Customer.
  - name: Verifications
    description: >-
      Submit immutable customer evidence snapshots for KYC or KYB evaluation, or
      start a KYB run for a business customer and poll its status.
  - name: Accounts
    description: >-
      Create and version customer-linked bank accounts, virtual accounts, and
      wallets without coupling the contract to a provider.
  - name: Documents
    description: Submit immutable document bytes or URL references and metadata.
  - name: Transactions
    description: Create and version money-movement records.
  - name: Sources
    description: >-
      Record source-attested, append-only completeness checkpoints used to
      qualify downstream evidence windows.
  - name: Outcomes
    description: >-
      Record source outcomes against customers, accounts, transactions, or
      documents.
  - name: Screening
    description: >-
      Submit provider-neutral verification, screening, alert, and
      reviewer-disposition evidence for Routine 6 qualification.
  - name: Controls
    description: >-
      Submit the source-owned monitoring control catalog and immutable execution
      evidence used to assess control coverage.
  - name: Requests
    description: >-
      Submit immutable historical request-for-information lifecycle events used
      to measure repeat requests and expiry.
  - name: Webhooks
    description: >-
      Manage source-scoped outbound destinations, receive later KYB evaluation
      lifecycle changes, and list recorded events to catch up on missed
      deliveries.
paths:
  /api/ingestion/webhook-events/{eventId}:
    get:
      tags:
        - Webhooks
      summary: Get a webhook event
      description: >-
        Returns events recorded for the calling ingestion source, including
        events that no endpoint received because none was ACTIVE and subscribed
        when they occurred. Each item has the same fields and values as the
        delivered envelope, and its id matches Karsa-Webhook-Id; JSON key order
        can differ and items are not signed. Events are readable for the webhook
        history window, 30 days by default.
      operationId: getWebhookEvent
      parameters:
        - schema:
            type: string
            minLength: 1
          required: true
          name: eventId
          in: path
      responses:
        '200':
          description: The recorded event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEvent'
              examples:
                completed:
                  value:
                    id: 7ca98328-1d7f-4ccb-8bd9-299373dbade2
                    type: kyb.evaluation.completed
                    version: '1'
                    createdAt: '2026-09-25T12:02:10.000Z'
                    source:
                      id: source_record_example_01
                      key: source-stable-key
                    subject:
                      type: customer
                      id: customer_resource_example_01
                    data:
                      evaluationId: evaluation_example_01
                      workflowRunId: workflow_run_example_01
                      caseId: case_example_01
                      supersedesWorkflowRunId: null
                      status: COMPLETED
                      outcome: ATTENTION_REQUIRED
                      failureCode: null
                      kybRun:
                        id: workflow_run_example_01
                        status: needs_review
                        customerId: customer_resource_example_01
                        externalCustomerId: business-example-001
                        caseId: case_example_01
                        createdAt: '2026-09-25T12:00:00.000Z'
                        startedAt: '2026-09-25T12:00:02.000Z'
                        completedAt: '2026-09-25T12:02:10.000Z'
                        result:
                          outcome: ATTENTION_REQUIRED
                          openIssueCount: 2
                          caseId: case_example_01
                        failure: null
        '401':
          description: >-
            AUTHENTICATION_REQUIRED: A source-bound bearer credential is
            required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                AUTHENTICATION_REQUIRED:
                  value:
                    type: https://karsa.app/problems/authentication-required
                    title: Ingestion Rejected
                    status: 401
                    detail: A source-bound bearer credential is required
                    code: AUTHENTICATION_REQUIRED
                    requestId: req_example_01
        '403':
          description: >-
            MACHINE_PRINCIPAL_REQUIRED: A source-bound machine principal is
            required TENANT_NOT_ACTIVE: The workspace is not active
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                MACHINE_PRINCIPAL_REQUIRED:
                  value:
                    type: https://karsa.app/problems/machine-principal-required
                    title: Ingestion Rejected
                    status: 403
                    detail: A source-bound machine principal is required
                    code: MACHINE_PRINCIPAL_REQUIRED
                    requestId: req_example_01
                TENANT_NOT_ACTIVE:
                  value:
                    type: https://karsa.app/problems/tenant-not-active
                    title: Ingestion Rejected
                    status: 403
                    detail: The workspace is not active
                    code: TENANT_NOT_ACTIVE
                    requestId: req_example_01
        '404':
          description: 'WEBHOOK_EVENT_NOT_FOUND: The webhook event was not found'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                WEBHOOK_EVENT_NOT_FOUND:
                  value:
                    type: https://karsa.app/problems/webhook-event-not-found
                    title: Ingestion Rejected
                    status: 404
                    detail: The webhook event was not found
                    code: WEBHOOK_EVENT_NOT_FOUND
                    requestId: req_example_01
        '429':
          description: 'RATE_LIMITED: The ingestion source exceeded its configured rate'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                RATE_LIMITED:
                  value:
                    type: https://karsa.app/problems/rate-limited
                    title: Ingestion Rejected
                    status: 429
                    detail: The ingestion source exceeded its configured rate
                    code: RATE_LIMITED
                    requestId: req_example_01
        '500':
          description: >-
            INGESTION_INTERNAL_ERROR: The ingestion request could not be
            completed
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                INGESTION_INTERNAL_ERROR:
                  value:
                    type: https://karsa.app/problems/ingestion-internal-error
                    title: Ingestion Unavailable
                    status: 500
                    detail: The ingestion request could not be completed
                    code: INGESTION_INTERNAL_ERROR
                    requestId: req_example_01
      security:
        - ingestionBearer: []
components:
  schemas:
    WebhookEvent:
      type: object
      properties:
        id:
          type: string
          format: uuid
        type:
          anyOf:
            - type: string
              enum:
                - kyb.evaluation.queued
                - kyb.evaluation.completed
                - kyb.evaluation.failed
            - type: string
              enum:
                - webhook.test
        version:
          type: string
          enum:
            - '1'
        createdAt:
          type: string
          format: date-time
        source:
          type: object
          properties:
            id:
              type: string
              minLength: 1
            key:
              type: string
              minLength: 1
          required:
            - id
            - key
          additionalProperties: false
        subject:
          type: object
          properties:
            type:
              type: string
              enum:
                - customer
            id:
              type: string
              minLength: 1
          required:
            - type
            - id
          additionalProperties: false
        data:
          type: object
          properties:
            evaluationId:
              type:
                - string
                - 'null'
              minLength: 1
            workflowRunId:
              type:
                - string
                - 'null'
              minLength: 1
            caseId:
              type:
                - string
                - 'null'
              minLength: 1
            supersedesWorkflowRunId:
              type:
                - string
                - 'null'
              minLength: 1
            status:
              type: string
              enum:
                - QUEUED
                - COMPLETED
                - FAILED
                - TEST
            outcome:
              type:
                - string
                - 'null'
            failureCode:
              type:
                - string
                - 'null'
            kybRun:
              type: object
              properties:
                id:
                  type: string
                  minLength: 1
                status:
                  anyOf:
                    - type: string
                      enum:
                        - pending
                        - running
                        - needs_review
                        - completed
                        - failed
                    - type: string
                      pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,119}$
                customerId:
                  type: string
                  minLength: 1
                externalCustomerId:
                  type:
                    - string
                    - 'null'
                  minLength: 1
                caseId:
                  type: string
                  minLength: 1
                createdAt:
                  type: string
                  format: date-time
                startedAt:
                  type:
                    - string
                    - 'null'
                  format: date-time
                completedAt:
                  type:
                    - string
                    - 'null'
                  format: date-time
                result:
                  type:
                    - object
                    - 'null'
                  properties:
                    outcome:
                      anyOf:
                        - type: string
                          enum:
                            - ATTENTION_REQUIRED
                            - NO_ATTENTION
                            - APPROVED
                            - REVIEW_REQUIRED
                            - RFI_REQUIRED
                            - RESEARCH_REQUIRED
                            - HUMAN_REVIEW_REQUIRED
                        - type: string
                          pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,119}$
                    openIssueCount:
                      type: integer
                      minimum: 0
                    caseId:
                      type: string
                      minLength: 1
                  required:
                    - outcome
                    - openIssueCount
                    - caseId
                  additionalProperties: false
                failure:
                  type:
                    - object
                    - 'null'
                  properties:
                    code:
                      type: string
                      minLength: 1
                  required:
                    - code
                  additionalProperties: false
              required:
                - id
                - status
                - customerId
                - externalCustomerId
                - caseId
                - createdAt
                - startedAt
                - completedAt
                - result
                - failure
              additionalProperties: false
          required:
            - evaluationId
            - workflowRunId
            - status
            - outcome
            - failureCode
          additionalProperties: false
      required:
        - id
        - type
        - version
        - createdAt
        - source
        - subject
        - data
      additionalProperties: false
    Problem:
      type: object
      properties:
        type:
          type: string
          minLength: 1
        title:
          type: string
          minLength: 1
        status:
          type: integer
        detail:
          type: string
          minLength: 1
        code:
          type: string
          minLength: 1
        requestId:
          type: string
          minLength: 1
        existingRunId:
          type: string
          minLength: 1
        issues:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              message:
                type: string
            required:
              - path
              - message
            additionalProperties: false
          maxItems: 20
      required:
        - type
        - title
        - status
        - detail
        - code
        - requestId
      additionalProperties: false
  securitySchemes:
    ingestionBearer:
      type: http
      scheme: bearer
      description: >-
        Source-bound WorkOS API key or configured machine OIDC token. OIDC
        webhook management requires karsa:webhooks:manage.

````

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