feat: add xero webhooks open api specification

Author: rpocklin

xero-webhooks.yaml

@@ -0,0 +1,166 @@
+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: 9.1.1
+  termsOfService: https://developer.xero.com/xero-developer-platform-terms-conditions/
+  contact:
+    name: Xero Platform Team
+    email: api@xero.com
+    url: https://developer.xero.com
+servers:
+  - 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.
+    url: https://api.xero.com
+webhooks:
+  invoices:
+    post:
+      summary: Invoices Webhook Endpoint
+      description: Invoice (Create, Update)
+      operationId: publishInvoiceEvent
+      tags:
+        - Events
+      requestBody:
+        content:
+          application/json:
+           schema:
+             $ref: '#/components/schemas/WebhookEvent'
+      responses:
+        "200":
+          $ref: '#/components/responses/200WebhookDataReceivedOk'
+        "401":
+          $ref: '#/components/responses/401InvalidWebhookData'
+
+  subscriptions:
+    post:
+      summary: Subscriptions Webhook Endpoint
+      description: Subscription (Create, Update)
+      operationId: publishSubscriptionEvent
+      tags:
+        - Events
+      requestBody:
+        content:
+          application/json:
+           schema:
+             $ref: '#/components/schemas/WebhookEvent'
+      responses:
+        "200":
+          $ref: '#/components/responses/200WebhookDataReceivedOk'
+        "401":
+          $ref: '#/components/responses/401InvalidWebhookData'
+
+  contacts:
+    post:
+      summary: Contacts Webhook Endpoint
+      description: Contact (Create, Update)
+      operationId: publishContactEvent
+      tags:
+        - Events
+      requestBody:
+        content:
+          application/json:
+           schema:
+             $ref: '#/components/schemas/WebhookEvent'
+      responses:
+        "200":
+          $ref: '#/components/responses/200WebhookDataReceivedOk'
+        "401":
+          $ref: '#/components/responses/401InvalidWebhookData'
+
+components:
+  headers:
+    x-xero-signature:
+      description: A hashed signature of the payload is passed along in the headers of each request as x-xero-signature
+      schema:
+        type: string
+      example: "<Base_64_HMAC_SHA_256>"
+
+  schemas:
+    WebhookEvent:
+      required:
+        - events
+        - lastEventSequence
+        - firstEventSequence
+        - entropy
+      properties:
+        events:
+          type: array
+          items:
+            type: object
+            properties:
+              resourceUrl:
+                type: string
+                format: uri
+                description: The URL to retrieve the resource that has changed
+              resourceId:
+                type: string
+                format: uuid
+                description: The ID of the resource that has changed (e.g. ContactID)
+              eventDateUtc:
+                type: string
+                format: date-time
+                description: The date and time that event occurred (UTC time)
+              eventType:
+                type: string
+                description: The type of event of that occurred (e.g. Update)
+              eventCategory:
+                type: string
+                description: The category of event that occurred (e.g. CONTACT). You will only retrieve events from categories that your webhook is subscribed to.
+              tenantId:
+                type: string
+                format: uuid
+                description: The ID of the tenant that the event happened in relation to (OrganisationID or ApplicationID)
+              tenantType:
+                type: string
+                description: The type of tenant, depending on the type of event it will be one of ORGANISATION (for Contact or Invoice events), or APPLICATION (for Subscription events)
+            required:
+              - resourceUrl
+              - resourceId
+              - eventDateUtc
+              - eventType
+              - eventCategory
+              - tenantId
+              - tenantType
+          description: A list of events that have occurred.
+        lastEventSequence:
+          type: integer
+          minimum: 1
+          maximum: 2147483647
+          description: The sequence number of the last event in the list.
+        firstEventSequence:
+          type: integer
+          minimum: 1
+          maximum: 2147483647
+          description: The sequence number of the first event in the list.
+        entropy:
+          type: string
+          description: A random string used for security or validation purposes.
+  responses:
+    401InvalidWebhookData:
+      description: Return a 401 status to indicate that the webhook subscription failed
+
+    200WebhookDataReceivedOk:
+      description: Return a 200 status to indicate that the webhook subscription succeeded
+      headers:
+        x-xero-signature:
+          $ref: '#/components/headers/x-xero-signature'
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/WebhookEvent'
+            example:
+              {
+                "events": [
+                    {
+                      "resourceUrl": "https://api.xero.com/api.xro/2.0/Contacts/717f2bfc-c6d4-41fd-b238-3f2f0c0cf777",
+                      "resourceId": "717f2bfc-c6d4-41fd-b238-3f2f0c0cf777",
+                      "eventDateUtc": "2024-06-21T01:15:39.902",
+                      "eventType": "UPDATE",
+                      "eventCategory": "CONTACT",
+                      "tenantId": "c2cc9b6e-9458-4c7d-93cc-f02b81b0594f",
+                      "tenantType": "ORGANISATION"
+                    }
+                ],
+                "lastEventSequence": 1,
+                "firstEventSequence": 1,
+                "entropy": "S0m3r4Nd0mt3xt"
+              }