From 05135438334003b9f9eb4c7e5c977f63b5463666 Mon Sep 17 00:00:00 2001
From: Tianyang Liu <tianyang.liu@xero.com>
Date: Thu, 13 Aug 2026 10:55:58 +1200
Subject: [PATCH 1/2] feat!: add prepayments webhook endpoint and schema
 BREAKING CHANGE: adds PREPAYMENT as a new eventCategory oneOf value in
 xero-webhooks.yaml. Existing strict schema validators may reject this new
 enum value in webhook payloads; this is expected since subscribers must
 explicitly opt in to prepayment events.

---
 xero-webhooks.yaml | 98 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 96 insertions(+), 2 deletions(-)

diff --git a/xero-webhooks.yaml b/xero-webhooks.yaml
index e556027d0..d4a78930c 100644
--- a/xero-webhooks.yaml
+++ b/xero-webhooks.yaml
@@ -2,7 +2,7 @@ openapi: 3.1.1
 info:
   description: The Xero Webhooks API exposes event notifications relating to entities in the Xero Public API and can be used for a variety of purposes
   title: Xero Webhooks API
-  version: 16.0.0
+  version: 16.2.0
   termsOfService: https://developer.xero.com/xero-developer-platform-terms-conditions/
   contact:
     name: Xero Platform Team
@@ -99,6 +99,42 @@ webhooks:
           $ref: "#/components/responses/200WebhookDataReceivedOk"
         "401":
           $ref: "#/components/responses/401InvalidWebhookData"
+  prepayments:
+    post:
+      summary: Prepayments Webhook Endpoint
+      description: Prepayment (Create, Update)
+      operationId: publishPrepaymentEvent
+      tags:
+        - Events
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PrepaymentWebhookEvent"
+            examples:
+              prepaymentCreate:
+                summary: Prepayment Create Event
+                value:
+                  events:
+                    - resourceUrl: https://api.xero.com/api.xro/2.0/Prepayments/717f2bfc-c6d4-41fd-b238-3f2f0c0cf777
+                      resourceId: 717f2bfc-c6d4-41fd-b238-3f2f0c0cf777
+                      tenantId: c2cc9b6e-9458-4c7d-93cc-f02b81b0594f
+                      tenantType: ORGANISATION
+                      eventCategory: PREPAYMENT
+                      eventType: CREATE
+                      eventDateUtc: 2025-10-21T01:15:39.902
+                      data:
+                        Type: RECEIVE-PREPAYMENT
+                        Status: AUTHORISED
+                        UpdatedDateUTCString: 2025-10-21T01:15:39Z
+                  firstEventSequence: 76
+                  lastEventSequence: 76
+                  entropy: FXNGWLCCGVANWHKILRUB
+      responses:
+        "200":
+          $ref: "#/components/responses/200WebhookDataReceivedOk"
+        "401":
+          $ref: "#/components/responses/401InvalidWebhookData"
 components:
   headers:
     x-xero-signature:
@@ -157,6 +193,9 @@ components:
                   - type: string
                     const: CREDITNOTE
                     description: For organisation credit note-related events
+                  - type: string
+                    const: PREPAYMENT
+                    description: For organisation prepayment-related events
               tenantId:
                 type: string
                 format: uuid
@@ -252,6 +291,61 @@ components:
                                 description: Voided credit note
                     required:
                       - data
+    PrepaymentWebhookEvent:
+      allOf:
+        - $ref: "#/components/schemas/WebhookEvent"
+        - type: object
+          properties:
+            events:
+              type: array
+              items:
+                allOf:
+                  - $ref: "#/components/schemas/WebhookEvent/properties/events/items"
+                  - type: object
+                    properties:
+                      eventCategory:
+                        const: PREPAYMENT
+                      data:
+                        type: object
+                        description: Prepayment document lifecycle events for customer/supplier advance payments
+                        required:
+                          - Type
+                          - Status
+                          - UpdatedDateUTCString
+                        properties:
+                          Type:
+                            type: string
+                            description: The specific type of prepayment
+                            externalDocs:
+                              url: https://developer.xero.com/documentation/api/accounting/types#prepayments
+                            oneOf:
+                              - type: string
+                                const: RECEIVE-PREPAYMENT
+                                description: A customer prepayment
+                              - type: string
+                                const: SPEND-PREPAYMENT
+                                description: A supplier prepayment
+                          Status:
+                            type: string
+                            description: The current lifecycle status of the prepayment
+                            externalDocs:
+                              url: https://developer.xero.com/documentation/api/accounting/types#prepayment-status-codes
+                            oneOf:
+                              - type: string
+                                const: AUTHORISED
+                                description: Authorised prepayment
+                              - type: string
+                                const: PAID
+                                description: Paid prepayment
+                              - type: string
+                                const: VOIDED
+                                description: Voided prepayment
+                          UpdatedDateUTCString:
+                            type: string
+                            format: date-time
+                            description: The date and time the prepayment was last updated in UTC ISO format
+                    required:
+                      - data
   responses:
     401InvalidWebhookData:
       description: Return a 401 status to indicate that the webhook subscription failed
@@ -275,4 +369,4 @@ components:
                   tenantType: ORGANISATION
               lastEventSequence: 1
               firstEventSequence: 1
-              entropy: S0m3r4Nd0mt3xt
+              entropy: S0m3r4Nd0mt3xt
\ No newline at end of file

From a5cfbd905507821b986d514b9dc0d31f005fc38c Mon Sep 17 00:00:00 2001
From: Tianyang Liu <tianyang.liu@xero.com>
Date: Thu, 13 Aug 2026 11:05:38 +1200
Subject: [PATCH 2/2] chore: add trailing newline to xero-webhooks.yaml

---
 xero-webhooks.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/xero-webhooks.yaml b/xero-webhooks.yaml
index d4a78930c..d8aab7cde 100644
--- a/xero-webhooks.yaml
+++ b/xero-webhooks.yaml
@@ -369,4 +369,4 @@ components:
                   tenantType: ORGANISATION
               lastEventSequence: 1
               firstEventSequence: 1
-              entropy: S0m3r4Nd0mt3xt
\ No newline at end of file
+              entropy: S0m3r4Nd0mt3xt