openapi: 3.2.0
info:
  title: Truework Webhooks API
  description: 'Webhook event reference for Truework. Subscribers receive `order.completed` events when every verification on an order has finished, and `verification_request.state.change` events as individual verifications transition through their state machine (pending-approval, processing, action-required, completed, canceled, invalid). Each webhook instance is associated with a token delivered in the `X-Truework-Token` header so handlers can authenticate the call.

    '
  version: 2023-10-30
  contact:
    name: Truework Implementations
    email: implementations@truework.com
    url: https://www.truework.com/docs/api-reference/webhooks
  license:
    name: Truework Terms of Service
    url: https://www.truework.com/legal/terms
servers:
- url: https://your-webhook-handler.example.com
  description: Customer-hosted webhook handler endpoint
tags:
- name: Truework Webhooks
paths: {}
webhooks:
  order-completed:
    post:
      operationId: order-completed
      summary: Order Completed
      description: This webhook will be issued when all verifications associated with the order have been completed or canceled. Once you receive this webhook you can fetch the order results from the API.
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                version:
                  type: string
                  description: The version of the webhook payload
                hook:
                  $ref: '#/components/schemas/OrderCompletedPostPayloadContentApplicationJsonSchemaHook'
                data:
                  $ref: '#/components/schemas/OrderCompletedPostPayloadContentApplicationJsonSchemaData'
      tags:
      - Truework Webhooks
  verification-request-state-change:
    post:
      operationId: verification-request-state-change
      summary: Verification Request State Change
      description: This webhook will be issued when a verification request in an order changes state. A `completed` state indicates that new data is now available on the order. A `canceled` state indicates that a verification was not able to be completed, but may have applicant-provided information and/or documents.
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                version:
                  type: string
                  description: The version of the webhook payload
                hook:
                  $ref: '#/components/schemas/VerificationRequestStateChangePostPayloadContentApplicationJsonSchemaHook'
                data:
                  $ref: '#/components/schemas/VerificationRequestStateChangePostPayloadContentApplicationJsonSchemaData'
      tags:
      - Truework Webhooks
components:
  schemas:
    VerificationRequestStateChangePostPayloadContentApplicationJsonSchemaHook:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the webhook
        event:
          $ref: '#/components/schemas/VerificationRequestStateChangePostPayloadContentApplicationJsonSchemaHookEvent'
          description: The event that triggered the webhook
        target:
          type: string
          description: The target of the webhook
        triggered_at:
          type: string
          format: date-time
          description: Date and time of the event that triggered the webhook
      title: VerificationRequestStateChangePostPayloadContentApplicationJsonSchemaHook
    VerificationRequestStateChangePostPayloadContentApplicationJsonSchemaDataMetadata:
      type: object
      properties: {}
      title: VerificationRequestStateChangePostPayloadContentApplicationJsonSchemaDataMetadata
    VerificationRequestStateChangePostPayloadContentApplicationJsonSchemaHookEvent:
      type: string
      enum:
      - verification_request.state.change
      description: The event that triggered the webhook
      title: VerificationRequestStateChangePostPayloadContentApplicationJsonSchemaHookEvent
    OrderCompletedPostPayloadContentApplicationJsonSchemaData:
      type: object
      properties:
        order_id:
          type: string
          description: The ID of the order that was completed
        metadata:
          $ref: '#/components/schemas/OrderCompletedPostPayloadContentApplicationJsonSchemaDataMetadata'
      title: OrderCompletedPostPayloadContentApplicationJsonSchemaData
    VerificationRequestStateChangePostPayloadContentApplicationJsonSchemaData:
      type: object
      properties:
        order_id:
          type: string
          description: The ID of the order that contains the verification request
        state:
          $ref: '#/components/schemas/VerificationRequestStateChangePostPayloadContentApplicationJsonSchemaDataState'
        verification_request_id:
          type: string
          description: The ID of the verification request
        credentials_session_token:
          type: string
          description: The ID of the Truework Direct session
        metadata:
          $ref: '#/components/schemas/VerificationRequestStateChangePostPayloadContentApplicationJsonSchemaDataMetadata'
      title: VerificationRequestStateChangePostPayloadContentApplicationJsonSchemaData
    OrderCompletedPostPayloadContentApplicationJsonSchemaHookEvent:
      type: string
      enum:
      - order.completed
      description: The event that triggered the webhook
      title: OrderCompletedPostPayloadContentApplicationJsonSchemaHookEvent
    VerificationRequestStateChangePostPayloadContentApplicationJsonSchemaDataState:
      type: string
      enum:
      - pending-approval
      - processing
      - action-requred
      - completed
      - canceled
      - invalid
      title: VerificationRequestStateChangePostPayloadContentApplicationJsonSchemaDataState
    OrderCompletedPostPayloadContentApplicationJsonSchemaHook:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the webhook
        event:
          $ref: '#/components/schemas/OrderCompletedPostPayloadContentApplicationJsonSchemaHookEvent'
          description: The event that triggered the webhook
        target:
          type: string
          description: The target of the webhook
        triggered_at:
          type: string
          format: date-time
          description: Date and time of the event that triggered the webhook
      title: OrderCompletedPostPayloadContentApplicationJsonSchemaHook
    OrderCompletedPostPayloadContentApplicationJsonSchemaDataMetadata:
      type: object
      properties: {}
      title: OrderCompletedPostPayloadContentApplicationJsonSchemaDataMetadata