Xero-OpenAPI/xero-webhooks.yaml at master · nca-work/Xero-OpenAPI · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
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.3.0
  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
security: []
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)
                oneOf:
                  - type: string
                    const: CREATE
                    description: When a new resource is created
                  - type: string
                    const: UPDATE
                    description: When an existing resource is updated (including when they are archived)
              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
                oneOf:
                  - type: string
                    const: CONTACT
                    description: For organisation contact-related events
                  - type: string
                    const: INVOICE
                    description: For organisation invoice-related events
                  - type: string
                    const: SUBSCRIPTION
                    description: For application subscription-related events
              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
                oneOf:
                  - type: string
                    const: ORGANISATION
                    description: Represents a Xero organisation (for non-Subscription events)
                  - type: string
                    const: APPLICATION
                    description: Represents a Xero 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