From 4716bbc4ad6d79b6b83dff60ec9577380ee3ed3e Mon Sep 17 00:00:00 2001
From: spwoodcock <sam.woodcock@protonmail.com>
Date: Wed, 29 Jan 2025 17:57:00 +0000
Subject: [PATCH] docs: add examples for webhook request body on each event
 type

---
 README.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 46 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 8ef4924..f3b8957 100644
--- a/README.md
+++ b/README.md
@@ -2,8 +2,15 @@
 
 Call a remote API on ODK Central database events:
 
-- New submission.
-- Update entity.
+- New submission (XML).
+- Update entity (entity properties).
+- Submission review (approved, hasIssues, rejected).
+
+## Prerequisites
+
+- ODK Central running, connecting to an accessible Postgresql database.
+- A POST webhook endpoint on your service API, to call when the selected
+  event occurs.
 
 ## Usage
 
@@ -26,7 +33,7 @@ Then run with:
 ```
 
 > [!TIP]
-> It's possible to specify a webhook for only Entities or Submissions, or both.
+> It's possible to specify a single webhook event, or multiple.
 
 ### Docker
 
@@ -93,6 +100,42 @@ if err != nil {
 > To not provide a webhook for either entities or submissions,
 > pass `nil` instead.
 
+## Request Examples
+
+### Entity Update (updateEntityUrl)
+
+```json
+{
+    "type": "entity.update.version",
+    "id":"uuid:3c142a0d-37b9-4d37-baf0-e58876428181",
+    "data": {
+        "entityProperty1": "someStringValue",
+        "entityProperty2": "someStringValue",
+        "entityProperty3": "someStringValue"
+    }
+}
+```
+
+### New Submission (newSubmissionUrl)
+
+```json
+{
+    "type": "submission.create",
+    "id":"uuid:3c142a0d-37b9-4d37-baf0-e58876428181",
+    "data": {"xml":"<?xml version='1.0' encoding='UTF-8' ?><data ...."}
+}
+```
+
+### Review Submission (reviewSubmissionUrl)
+
+```json
+{
+    "type":"submission.update",
+    "id":"uuid:5ed3b610-a18a-46a2-90a7-8c80c82ebbe9",
+    "data": {"reviewState":"hasIssues"}
+}
+```
+
 ## APIs With Authentication
 
 Many APIs will not be public and require some sort of authentication.