From 2ef54ce8672cfd74524dc3e36004383db6f802e0 Mon Sep 17 00:00:00 2001
From: Tom Winter <tom@aam-digital.com>
Date: Fri, 9 Feb 2024 09:46:41 +0100
Subject: [PATCH] docs: add event schema

---
 docs/api-specs/reporting-api-v1.yaml | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/docs/api-specs/reporting-api-v1.yaml b/docs/api-specs/reporting-api-v1.yaml
index 049a7b6..d2702ff 100644
--- a/docs/api-specs/reporting-api-v1.yaml
+++ b/docs/api-specs/reporting-api-v1.yaml
@@ -119,7 +119,9 @@ paths:
         - report
       summary: Trigger a new report calculation run.
       description: Trigger a new report calculation run. Check status of the asynchronous calculation via the /report-calculation endpoint
-        (CURRENTLY UNDER DEVELOPMENT) optionally receive status updates via a webhook if that has been set up for the authorized client
+        As an alternative to triggering a single report calculation, you can subscribe to receive
+        a notification event (which includes an automatically created calculationId) whenever the report's
+        results change (see /webhook/{webhookId}/subscribe/report).
       parameters:
         - in: path
           name: reportId
@@ -477,6 +479,25 @@ components:
         headerName:
           type: string
 
+    Event:
+      type: object
+      description: Representation of the payload we will send to the webhook
+      properties:
+        id:
+          type: string
+          format: uuid
+        eventName:
+          type: string
+          enum:
+            - NEW_REPORT_DATA_AVAILABLE
+        reportId:
+          type: string
+        calculationId:
+          type: string
+        created_at:
+          type: string
+          format: date
+
     # global
 
     Error: