Onfido Webhooks API

openapi: 3.0.0
info:
  contact:
    name: Onfido
    url: https://public.support.onfido.com
  description: "\nCreate trust at onboarding and beyond with a complete, AI-powered digital\nidentity solution built to help you know your customers online. \nAutomation allows you to acquire new customers and reduce costs while\nmeeting global KYC and AML compliance."
  license:
    name: MIT
  title: Onfido Webhooks API
  version: v3.6
servers:
- url: https://api.{region}.onfido.com/v3.6
  variables:
    region:
      default: eu
      enum:
      - eu
      - us
      - ca
security:
- Token: []
tags:
- name: Webhooks
paths:
  /webhooks:
    get:
      description: 'Lists all webhooks you''ve created.

        '
      operationId: list_webhooks
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhooks_list'
          description: A list of webhooks
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: List webhooks
      tags:
      - Webhooks
    post:
      callbacks:
        webhookEvent:
          '{$request.body#/url}':
            post:
              operationId: webhookEventPost
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/webhook_event'
                required: true
              responses:
                default:
                  description: Your server should acknowledge success by responding with an HTTP 20x response within 10 seconds.
              x-callback-request: true
      description: 'Registers a webhook. Returns a webhook object.

        '
      operationId: create_webhook
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhook_builder'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook'
          description: Created
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Register webhook
      tags:
      - Webhooks
  /webhooks/{webhook_id}:
    delete:
      description: 'Deletes a webhook.

        '
      operationId: delete_webhook
      parameters:
      - in: path
        name: webhook_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '204':
          description: Webhook deleted
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Delete a webhook
      tags:
      - Webhooks
    get:
      description: 'Retrieves a single webhook. Returns a webhook object.

        '
      operationId: find_webhook
      parameters:
      - in: path
        name: webhook_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook'
          description: Webhook object
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Retrieve a Webhook
      tags:
      - Webhooks
    put:
      description: 'Edits a webhook. Returns the updated webhook object.

        '
      operationId: update_webhook
      parameters:
      - in: path
        name: webhook_id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhook_updater'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook'
          description: Webhook Object
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Edit a webhook
      tags:
      - Webhooks
  /webhooks/resend:
    post:
      description: 'Resends events to all webhooks registered with a matching environment in your account.

        '
      operationId: resend_webhooks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhook_resend'
        required: true
      responses:
        '204':
          description: Webhooks are resent for the respective checks
        '422':
          description: Request was received but it could not be processed
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unexpected error
      summary: Resends webhooks
      tags:
      - Webhooks
components:
  schemas:
    ErrorProperties:
      example:
        type: type
        message: message
        fields:
          key: ''
      properties:
        type:
          type: string
        message:
          type: string
        fields:
          additionalProperties: true
          type: object
      title: ErrorProperties
      type: object
    webhook_event_object_status:
      description: The current state of the object, if available.
      enum:
      - processing
      - awaiting_input
      - awaiting_client_input
      - approved
      - declined
      - review
      - abandoned
      - error
      - started
      - cancelled
      - completed
      - awaiting_data
      - awaiting_approval
      - complete
      - withdrawn
      - in_progress
      - awaiting_applicant
      - paused
      - reopened
      example: complete
      type: string
    workflow_run_link:
      properties:
        url:
          description: Link to access the Workflow Run without the need to integrate with Onfido's SDKs.
          type: string
        completed_redirect_url:
          description: When the interactive section of the Workflow Run has completed successfully, the user will be redirected to this URL instead of seeing the default Onfido 'thank you' page.
          nullable: true
          type: string
        expired_redirect_url:
          description: When the link has expired, the user will be immediately redirected to this URL instead of seeing the default Onfido error message.
          nullable: true
          type: string
        expires_at:
          description: Date and time when the link will expire.
          format: date-time
          nullable: true
          type: string
        language:
          description: The code for the language when the workflow run is acessed using the link.
          enum:
          - en_US
          - de_DE
          - es_ES
          - fr_FR
          - it_IT
          - pt_PT
          - nl_NL
          nullable: true
          type: string
    webhook_event_type:
      enum:
      - audit_log.created
      - watchlist_monitor.matches_updated
      - workflow_run.completed
      - workflow_task.started
      - workflow_task.completed
      - check.started
      - check.reopened
      - check.withdrawn
      - check.completed
      - check.form_completed
      - report.withdrawn
      - report.resumed
      - report.cancelled
      - report.awaiting_approval
      - report.completed
      - workflow_timeline_file.created
      - workflow_signed_evidence_file.created
      - workflow_run_evidence_folder.created
      type: string
    webhook_create:
      properties:
        url:
          description: The url that will listen to notifications (must be https).
          type: string
      required:
      - url
    webhook_event_payload:
      properties:
        resource_type:
          allOf:
          - $ref: '#/components/schemas/webhook_event_resource_type'
          description: Indicates the resource affected by this event.
          example: workflow_task
          type: string
        action:
          allOf:
          - $ref: '#/components/schemas/webhook_event_type'
          description: The event that triggered this webhook.
          example: workflow_task.completed
          type: string
        object:
          $ref: '#/components/schemas/webhook_event_payload_object'
        resource:
          $ref: '#/components/schemas/webhook_event_payload_resource'
      required:
      - event
      - resource_id
      - resource_type
      type: object
    webhook_event:
      properties:
        payload:
          $ref: '#/components/schemas/webhook_event_payload'
      type: object
    webhook_event_resource_type:
      enum:
      - check
      - report
      - audit_log
      - workflow_run
      - workflow_task
      - watchlist_monitor
      - workflow_timeline_file
      - workflow_run_evidence_folder
      type: string
    webhook_builder:
      allOf:
      - $ref: '#/components/schemas/webhook_shared'
      - $ref: '#/components/schemas/webhook_create'
    webhook_event_payload_resource:
      description: The resource affected by this event.
      properties:
        id:
          description: The identifier of the resource.
          example: profile_4f4b2
          type: string
        applicant_id:
          description: The unique identifier for the Applicant.
          format: uuid
          type: string
        created_at:
          description: The date and time when the resource was created.
          example: '2022-12-05T16:41:43.000Z'
          format: date-time
          type: string
        updated_at:
          description: The date and time when the resource was last updated.
          example: '2022-12-19T16:41:44.000Z'
          format: date-time
          type: string
        dashboard_url:
          description: The URL for viewing the resource on Onfido Dashboard.
          example: https://dashboard.onfido.com/results/36a56899-d617-4988-85bf-b76640861bf5
          type: string
        workflow_id:
          description: The unique identifier for the Workflow.
          format: uuid
          type: string
        workflow_run_id:
          example: 2f152409-d6c4-4711-8750-48517f99a8d6
          format: uuid
          type: string
        workflow_version_id:
          description: The identifier for the Workflow version.
          example: 0
          type: integer
        task_def_id:
          description: The identifier for the Task Definition.
          example: task_123
          pattern: ^[0-9a-z_-]+$
          type: string
        task_def_version:
          description: The task definition version.
          nullable: true
          type: string
        input:
          description: Input object with the fields used by the Task execution.
          type: object
        output:
          description: Value field (it can be an Object, List, etc.) with the fields produced by the Task execution.
          nullable: true
          type: object
        reasons:
          description: The reasons the Workflow Run outcome was reached. Configurable when creating the Workflow Version.
          items:
            type: string
          type: array
        link:
          allOf:
          - $ref: '#/components/schemas/workflow_run_link'
          description: Object for the configuration of the Workflow Run link.
          type: object
        error:
          allOf:
          - $ref: '#/components/schemas/workflow_run_error'
          description: Error object that details why a Workflow Run is in Error status.
          type: object
      type: object
    Webhooks_list:
      example:
        webhooks:
        - payload_version: 0
          environments:
          - environments
          - environments
          id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          href: href
          enabled: true
          events:
          - audit_log.created
          - audit_log.created
          url: url
          token: token
        - payload_version: 0
          environments:
          - environments
          - environments
          id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          href: href
          enabled: true
          events:
          - audit_log.created
          - audit_log.created
          url: url
          token: token
      properties:
        webhooks:
          items:
            $ref: '#/components/schemas/webhook'
          type: array
      required:
      - webhooks
      title: Webhooks list
      type: object
    webhook_event_payload_object:
      description: The object affected by this event.
      properties:
        id:
          description: The unique identifier of the resource.
          type: string
        status:
          $ref: '#/components/schemas/webhook_event_object_status'
        started_at_iso8601:
          description: The date and time when the operation was started, if available.
          example: '2019-10-28T14:55:09.000Z'
          format: date-time
          type: string
        completed_at_iso8601:
          description: The date and time when the operation was completed, if available.
          example: '2019-10-28T15:00:39.000Z'
          format: date-time
          type: string
        href:
          description: The uri of the resource.
          type: string
      required:
      - href
      - id
      type: object
    webhook_updater:
      allOf:
      - $ref: '#/components/schemas/webhook_shared'
      - $ref: '#/components/schemas/webhook_update'
    webhook_update:
      properties:
        url:
          description: The url that will listen to notifications (must be https).
          type: string
    Webhooks_resend_item:
      properties:
        resource_id:
          description: ID of the resource whose webhooks are to be retriggered.
          format: uuid
          type: string
        event:
          allOf:
          - $ref: '#/components/schemas/webhook_event_type'
          description: The events that should retrigger webhooks. Accepts values check.completed.
          example: check.completed
          type: string
      required:
      - event
      - resource_id
      title: Webhooks resend item
      type: object
    webhook_shared:
      properties:
        enabled:
          description: Determine if the webhook is active.
          type: boolean
        events:
          description: 'The events that will be published to the webhook. If the events parameter is omitted all the events will be subscribed.

            '
          items:
            $ref: '#/components/schemas/webhook_event_type'
          type: array
        environments:
          description: 'The environments from which the webhook will receive events. Allowed values are sandbox and live. If the environments parameter is omitted the webhook will receive events from both environments.

            '
          items:
            type: string
          type: array
        payload_version:
          description: Webhook version used to control the payload object when sending webhooks.
          type: integer
      type: object
    webhook_response:
      properties:
        id:
          description: The unique identifier of the webhook.
          format: uuid
          type: string
        url:
          description: The url that will listen to notifications (must be https).
          type: string
        token:
          description: Webhook secret token used to sign the webhook's payload.
          type: string
        href:
          description: The API endpoint to retrieve the webhook.
          type: string
      required:
      - id
      type: object
    Error:
      example:
        error:
          type: type
          message: message
          fields:
            key: ''
      properties:
        error:
          $ref: '#/components/schemas/ErrorProperties'
      title: Error
      type: object
    webhook:
      allOf:
      - $ref: '#/components/schemas/webhook_shared'
      - $ref: '#/components/schemas/webhook_response'
      example:
        payload_version: 0
        environments:
        - environments
        - environments
        id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        href: href
        enabled: true
        events:
        - audit_log.created
        - audit_log.created
        url: url
        token: token
    webhook_resend:
      properties:
        data:
          items:
            $ref: '#/components/schemas/Webhooks_resend_item'
          title: Webhooks resend list
          type: array
      type: object
    workflow_run_error:
      properties:
        type:
          description: The type of error.
          type: string
        message:
          description: A textual description of the error.
          type: string
      type: object
  securitySchemes:
    Token:
      in: header
      name: Authorization
      type: apiKey
externalDocs:
  url: https://documentation.onfido.com