Xero-OpenAPI/xero-webhooks.yaml at master · GiovanniGo/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
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.2.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
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