Online Documentation Does Not Match OpenAPI / Swagger Schema For Webhook Payloads

[influential-eliot]

Broad Overview

Each of the below Webhook API documentation pages has a potential error (which does not pass schema validation when implemented) which is (unfortunately) repeated in other online examples that I've found.

Examples

Examples With Links To Pages

The below list contains each Webhook endpoint type that has this issue, a link to it, an image of it, and the example JSON payload listed on the page.

• _{expand for detail}
  NB - Each Webhook endpoint in the API OpenAPI spec has the same example (for the /contacts endpoint)

  Schema 'Example Value' JSON Code

  {
    "events": [
      {
        "resourceUrl": "https://example.com/",
        "resourceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "eventDateUtc": "2026-02-02T10:06:17.069Z",
        "eventType": "CREATE",
        "eventCategory": "CONTACT",
        "tenantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "tenantType": "ORGANISATION"
      }
    ],
    "lastEventSequence": 1,
    "firstEventSequence": 1,
    "entropy": "string"
  }

1. /contacts

   • Link
   • Screenshot

     
   • /contactsPage 'Example Payload' JSON Code

     /contactsPage 'Example Payload' JSON Code

     {
         "resourceUrl": "https://api.xero.com/api.xro/2.0/Contacts",
         "resourceId": "717f2bfc-c6d4-41fd-b238-3f2f0c0cf777",
         "eventDateUtc": "2025-10-21T01:15:39.902",
         "eventType": "Update",
         "eventCategory": "CONTACT",
         "tenantId": "c2cc9b6e-9458-4c7d-93cc-f02b81b0594f",
         "tenantType": "ORGANISATION"
     }

2. /invoices

   • Link
   • Screenshot

     
   • /invoicesPage 'Example Payload' JSON Code

     /invoicesPage 'Example Payload' JSON Code

     {
         "resourceUrl": "https://api.xero.com/api.xro/2.0/Invoices",
         "resourceId": "717f2bfc-c6d4-41fd-b238-3f2f0c0cf777",
         "eventDateUtc": "2025-10-21T01:15:39.902",
         "eventType": "Update",
         "eventCategory": "INVOICE",
         "tenantId": "c2cc9b6e-9458-4c7d-93cc-f02b81b0594f",
         "tenantType": "ORGANISATION"
     }

3. /subscriptions

   • Link
   • Screenshot

     
   • /subscriptionsPage 'Example Payload' JSON Code

     /subscriptionsPage 'Example Payload' JSON Code

     {
         "resourceUrl": "https://api.xero.com/appstore/2.0/Subscriptions",
         "resourceId": "717f2bfc-c6d4-41fd-b238-3f2f0c0cf777",
         "eventDateUtc": "2025-10-21T01:15:39.902",
         "eventType": "Update",
         "eventCategory": "SUBSCRIPTION",
         "tenantId": "c2cc9b6e-9458-4c7d-93cc-f02b81b0594f",
         "tenantType": "APPLICATION"
     }

4. /credit-notes

   • Link
   • Screenshot

     
   • /credit-notesPage 'Example Payload' JSON Code

     /credit-notesPage 'Example Payload' JSON Code

     {
         "resourceUrl": "https://api.xero.com/api.xro/2.0/CreditNotes/717f2bfc-c6d4-41fd-b238-3f2f0c0cf777",
         "resourceId": "717f2bfc-c6d4-41fd-b238-3f2f0c0cf777",
         "eventDateUtc": "2025-10-21T01:15:39.902",
         "eventType": "Update",
         "eventCategory": "CREDITNOTE",
         "tenantId": "c2cc9b6e-9458-4c7d-93cc-f02b81b0594f",
         "tenantType": "ORGANISATION",
         "data": {
             "Type": "ACCPAYCREDIT",
             "Status": "SUBMITTED",
             "UpdatedDateUTC": "2025-10-21T01:15:37.236"
         }
     }

I'm making (probably/hopefully correct) assumptions that the whole schema is the correct thing and the online resources showing things (like the below, hidden, image) are incorrect:

Image Of This Occurring On Xero Docs Outside Of Documentation

Image Of This Occurring On Xero Docs Outside Of Documentation

But, it may well be confusing to some, or may lead to incorrect implementations for others.

Best
Eliot

[github-actions]

PETOSS-897

[github-actions]

Thanks for raising an issue, a ticket has been created to track your request