[CAT-1306] Add webhooks event resource and a few improvements (#112)

* Define webhook resource type, object type and status as an enum
* Add webhooks event resource

schemas/checks/definitions.yaml

@@ -87,14 +87,7 @@ check_response:
       description: The uri of this resource.
     status:
       type: string
-      enum:
-        - in_progress
-        - awaiting_applicant
-        - complete
-        - withdrawn
-        - paused
-        - reopened
-      description: The current state of the check in the checking process.
+      $ref: "#/check_status"
     result:
       type: string
       enum:
@@ -121,3 +114,14 @@ check_response:
     version:
       type: string
       example: 3.6
+
+check_status:
+  type: string
+  enum:
+    - in_progress
+    - awaiting_applicant
+    - complete
+    - withdrawn
+    - paused
+    - reopened
+  description: The current state of the check in the checking process.

schemas/webhooks/definitions.yaml

@@ -53,6 +53,16 @@ webhook_update:
     url:
       $ref: "#/webhook_url"
 
+webhook_event_resource_type:
+  type: string
+  enum:
+    - check
+    - report
+    - audit_log
+    - workflow_run
+    - workflow_task
+    - watchlist_monitor
+
 webhook_event_type:
   type: string
   enum:

schemas/webhooks/webhook_event.yaml

@@ -9,13 +9,16 @@ properties:
     properties:
       resource_type:
         type: string
+        allOf:
+          - $ref: definitions.yaml#/webhook_event_resource_type
         description: Indicates the resource affected by this event.
+        example: workflow_task
       action:
         type: string
         allOf:
           - $ref: definitions.yaml#/webhook_event_type
         description: The event that triggered this webhook.
-        example: report.completed
+        example: workflow_task.completed
       object:
         type: object
         required:
@@ -27,9 +30,7 @@ properties:
             type: string
             description: The unique identifier of the resource.
           status:
-            type: string
-            description: The current state of the object, if available.
-            example: complete
+            $ref: "#/webhook_event_object_status"
           started_at_iso8601:
             type: string
             format: date-time
@@ -46,3 +47,98 @@ properties:
       resource:
         type: object
         description: The resource affected by this event.
+        properties:
+          id:
+            type: string
+            description: The identifier of the resource.
+            example: profile_4f4b2
+          applicant_id:
+            type: string
+            format: uuid
+            description: The unique identifier for the Applicant.
+          created_at:
+            type: string
+            format: date-time
+            description: The date and time when the resource was created.
+            example: "2022-12-05T16:41:43Z"
+          updated_at:
+            type: string
+            format: date-time
+            description: The date and time when the resource was last updated.
+            example: "2022-12-19T16:41:44Z"
+          dashboard_url:
+            type: string
+            description: The URL for viewing the resource on Onfido Dashboard.
+            example: "https://dashboard.onfido.com/results/36a56899-d617-4988-85bf-b76640861bf5"
+          workflow_id:
+            type: string
+            format: uuid
+            description: The unique identifier for the Workflow.
+          workflow_run_id:
+            type: string
+            format: uuid
+            example: 2f152409-d6c4-4711-8750-48517f99a8d6
+          workflow_version_id:
+            type: integer
+            description: The identifier for the Workflow version.
+            example: 0
+          task_def_id:
+            $ref: ../tasks/definitions.yaml#/task_def_id
+          task_def_version:
+            type: string
+            nullable: true
+            description: The task definition version.
+          input:
+            type: object
+            description: Input object with the fields used by the Task execution.
+          output:
+            type: object
+            nullable: true
+            description: Output object with the fields produced by the Task execution.
+          reasons:
+            type: array
+            items:
+              type: string
+            description: The reasons the Workflow Run outcome was reached. Configurable when creating the Workflow Version.
+          link:
+            type: object
+            allOf:
+              - $ref: ../workflow_runs/definitions.yaml#/workflow_run_link
+            description: Object for the configuration of the Workflow Run link.
+          error:
+            type: object
+            allOf:
+              - $ref: ../workflow_runs/definitions.yaml#/workflow_run_error
+            description: Error object that details why a Workflow Run is in Error status.
+
+webhook_event_object_status:
+  type: string
+  enum:
+    # ../workflow_runs/definitions.yaml#/workflow_run_status
+    - processing
+    - awaiting_input
+    - awaiting_client_input
+    - approved
+    - declined
+    - review
+    - abandoned
+    - error
+    # workflow_runs' tasks status
+    - started
+    - cancelled
+    - completed
+    # ../reports/definitions.yaml#/report_status
+    - awaiting_data
+    - awaiting_approval
+    - cancelled
+    - complete
+    - withdrawn
+    # ../checks/definitions.yaml#/check_status
+    - in_progress
+    - awaiting_applicant
+    - complete
+    - withdrawn
+    - paused
+    - reopened
+  description: The current state of the object, if available.
+  example: complete

schemas/workflow_runs/definitions.yaml

@@ -27,32 +27,9 @@ workflow_run_shared:
       description: Customer-provided user identifier.
     link:
       type: object
+      allOf:
+        - $ref: "#/workflow_run_link"
       description: Object for the configuration of the Workflow Run link.
-      properties:
-        url:
-          type: string
-          description: Link to access the Workflow Run without the need to integrate with Onfido's SDKs.
-        completed_redirect_url:
-          type: string
-          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.
-        expired_redirect_url:
-          type: string
-          description: When the link has expired, the user will be immediately redirected to this URL instead of seeing the default Onfido error message.
-        expires_at:
-          type: string
-          format: date-time
-          description: Date and time when the link will expire.
-        language:
-          type: string
-          enum:
-            - en_US
-            - de_DE
-            - es_ES
-            - fr_FR
-            - it_IT
-            - pt_PT
-            - nl_NL
-          description: The code for the language when the workflow run is acessed using the link.
     created_at:
       type: string
       format: date-time
@@ -86,15 +63,8 @@ workflow_run_response:
       type: string
       description: The URL for viewing the Workflow Run results on your Onfido Dashboard.
     status:
-      type: string
-      enum:
-        - awaiting_input
-        - processing
-        - abandoned
-        - error
-        - approved
-        - review
-        - declined
+      allOf:
+        - $ref: "#/workflow_run_status"
       description: The status of the Workflow Run.
     output:
       type: object
@@ -106,15 +76,63 @@ workflow_run_response:
         type: string
     error:
       type: object
+      allOf:
+        - $ref: "#/workflow_run_error"
       description: Error object. Only set when the Workflow Run status is 'error'.
-      properties:
-        type:
-          type: string
-          description: The type of error.
-        message:
-          type: string
-          description: A textual description of the error.
     sdk_token:
       type: string
       nullable: true
       description: Client token to use when loading this workflow run in the Onfido SDK.
+
+workflow_run_link:
+  properties:
+    url:
+      type: string
+      description: Link to access the Workflow Run without the need to integrate with Onfido's SDKs.
+    completed_redirect_url:
+      type: string
+      nullable: true
+      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.
+    expired_redirect_url:
+      type: string
+      nullable: true
+      description: When the link has expired, the user will be immediately redirected to this URL instead of seeing the default Onfido error message.
+    expires_at:
+      type: string
+      format: date-time
+      nullable: true
+      description: Date and time when the link will expire.
+    language:
+      type: string
+      enum:
+        - en_US
+        - de_DE
+        - es_ES
+        - fr_FR
+        - it_IT
+        - pt_PT
+        - nl_NL
+      nullable: true
+      description: The code for the language when the workflow run is acessed using the link.
+
+workflow_run_status:
+  type: string
+  enum:
+    - processing
+    - awaiting_input
+    - awaiting_client_input
+    - approved
+    - declined
+    - review
+    - abandoned
+    - error
+
+workflow_run_error:
+  type: object
+  properties:
+    type:
+      type: string
+      description: The type of error.
+    message:
+      type: string
+      description: A textual description of the error.