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: 19.1.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"
  creditNotes:
    post:
      summary: Credit Notes Webhook Endpoint
      description: Credit Note (Create, Update)
      operationId: publishCreditNoteEvent
      tags:
        - Events
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreditNoteWebhookEvent"
            examples:
              creditNoteCreate:
                summary: Credit Note Create Event
                value:
                  events:
                    - resourceUrl: https://api.xero.com/api.xro/2.0/CreditNotes/55d84274-a3da-4829-a7c0-0cab601b95cc
                      resourceId: 55d84274-a3da-4829-a7c0-0cab601b95cc
                      tenantId: aef86862-2015-4b6b-88bc-d89032cecc50
                      tenantType: ORGANISATION
                      eventCategory: CREDITNOTE
                      eventType: CREATE
                      eventDateUtc: 2025-12-02T00:44:09.923
                      data:
                        Type: ACCPAYCREDIT
                        Status: DRAFT
                  firstEventSequence: 76
                  lastEventSequence: 76
                  entropy: FXNGWLCCGVANWHKILRUB
      responses:
        "200":
          $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"
  overpayments:
    post:
      summary: Overpayments Webhook Endpoint
      description: Overpayment (Create, Update)
      operationId: publishOverpaymentEvent
      tags:
        - Events
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OverpaymentWebhookEvent"
            examples:
              overpaymentCreate:
                summary: Overpayment Create Event
                value:
                  events:
                    - resourceUrl: https://api.xero.com/api.xro/2.0/Overpayments/717f2bfc-c6d4-41fd-b238-3f2f0c0cf777
                      resourceId: 717f2bfc-c6d4-41fd-b238-3f2f0c0cf777
                      tenantId: c2cc9b6e-9458-4c7d-93cc-f02b81b0594f
                      tenantType: ORGANISATION
                      eventCategory: OVERPAYMENT
                      eventType: CREATE
                      eventDateUtc: 2025-10-21T01:15:39.902
                      data:
                        Type: RECEIVE-OVERPAYMENT
                        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:
      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
                  - type: string
                    const: CREDITNOTE
                    description: For organisation credit note-related events
                  - type: string
                    const: PREPAYMENT
                    description: For organisation prepayment-related events
                  - type: string
                    const: OVERPAYMENT
                    description: For organisation overpayment-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
    CreditNoteWebhookEvent:
      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: CREDITNOTE
                      data:
                        type: object
                        description: Additional data for credit note events
                        required:
                          - Type
                          - Status
                        properties:
                          Type:
                            type: string
                            description: The type of credit note
                            externalDocs:
                              url: https://developer.xero.com/documentation/api/accounting/types#credit-notes
                            oneOf:
                              - type: string
                                const: ACCPAYCREDIT
                                description: An Accounts Payable(supplier) Credit Note
                              - type: string
                                const: ACCRECCREDIT
                                description: An Account Receivable(customer) Credit Note
                          Status:
                            type: string
                            description: The status of the credit note
                            externalDocs:
                              url: https://developer.xero.com/documentation/api/accounting/types#invoice-status-codes
                            oneOf:
                              - type: string
                                const: DRAFT
                                description: Draft credit note
                              - type: string
                                const: SUBMITTED
                                description: Submitted credit note
                              - type: string
                                const: DELETED
                                description: Deleted credit note
                              - type: string
                                const: AUTHORISED
                                description: Authorised credit note
                              - type: string
                                const: PAID
                                description: Paid credit note
                              - type: string
                                const: VOIDED
                                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
    OverpaymentWebhookEvent:
      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: OVERPAYMENT
                      data:
                        type: object
                        description: Overpayment document lifecycle events for excess customer/supplier payments
                        required:
                          - Type
                          - Status
                          - UpdatedDateUTCString
                        properties:
                          Type:
                            type: string
                            description: The specific type of overpayment
                            externalDocs:
                              url: https://developer.xero.com/documentation/api/accounting/types#overpayments
                            oneOf:
                              - type: string
                                const: RECEIVE-OVERPAYMENT
                                description: A customer overpayment
                              - type: string
                                const: SPEND-OVERPAYMENT
                                description: A supplier overpayment
                          Status:
                            type: string
                            description: The current lifecycle status of the overpayment
                            externalDocs:
                              url: https://developer.xero.com/documentation/api/accounting/types#overpayment-status-codes
                            oneOf:
                              - type: string
                                const: AUTHORISED
                                description: Authorised overpayment
                              - type: string
                                const: PAID
                                description: Paid overpayment
                              - type: string
                                const: VOIDED
                                description: Voided overpayment
                          UpdatedDateUTCString:
                            type: string
                            format: date-time
                            description: The date and time the overpayment was last updated in UTC ISO format
                    required:
                      - data
  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