> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Xero Webhook Setup Guide

> Configure Xero to deliver events to StackOne.

## Prerequisites

The connector should already be set up, with a Connector Profile and a Linked Account. See [Getting Started](/connectors/xero#getting-started) on the Xero connector page.

<section data-guide-section data-guide-scopes="">
  <h2>Retrieve the StackOne Native Webhook URL</h2>

  <p>The <strong>Native Webhook URL</strong> is generated once a Xero account has been linked in StackOne. Each linked account has its own URL.</p>

  <ul>
    <li>Open the linked account in StackOne.</li>
    <li>Copy the value from <strong>Native Webhook URL</strong>.</li>
  </ul>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Create the webhook in your Xero app</h2>

  <p>Add the Native Webhook URL to the Xero app used by the connector profile, so Xero posts events to StackOne.</p>

  <Steps>
    <Step title="Open the app's webhook settings">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Sign in to the <a href="https://developer.xero.com/app/manage" target="_blank" rel="noopener noreferrer">Xero Developer portal</a> and open <strong>My Apps</strong>.</p>

        <ul>
          <li>Select the app whose Client ID is set on the StackOne connector profile.</li>
          <li>In the left menu, click <strong>Webhooks</strong>.</li>
        </ul>
      </div>
    </Step>

    <Step title="Choose the events and save">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Under <strong>Notify this app about changes to</strong>, tick the categories you want to receive.</p>

        <ul>
          <li>Tick any of <strong>Contacts</strong>, <strong>Invoices</strong>, <strong>Credit notes</strong>, <strong>Prepayments</strong> and <strong>Overpayments</strong>.</li>
          <li>Paste the Native Webhook URL into <strong>Delivery URL</strong>.</li>
          <li>Click <strong>Save</strong>. Xero then shows the <strong>Webhooks key</strong> and the status 'Intent to receive' required.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Add the Webhooks key and confirm delivery</h2>

  <p>Xero only delivers events after StackOne passes its Intent to receive check, which needs the Webhooks key on the linked account.</p>

  <Steps>
    <Step title="Add the Webhooks key to the linked account">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Copy the <strong>Webhooks key</strong> from the Xero app's <strong>Webhooks</strong> page.</p>

        <ul>
          <li>In StackOne, edit the linked Xero account and paste the key into <strong>Webhooks Key</strong>.</li>
        </ul>
      </div>
    </Step>

    <Step title="Send Intent to receive">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Back on the Xero app's <strong>Webhooks</strong> page, click <strong>Send 'Intent to receive'</strong>.</p>

        <ul>
          <li>The status changes to <strong>OK</strong> within about 30 seconds.</li>
          <li>If it stays at 'Intent to receive' required, check that the Webhooks Key on the account matches the key shown in Xero and that the Delivery URL is the account's Native Webhook URL.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Available webhook events</h2>

  <p>Each event's record ID is the Xero ID of the affected record (resourceId). Xero sends only<br />identifiers, so fetch the record for its current state.</p>

  <Steps>
    <Step title="Contact events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for contacts.</p>

        <ul>
          <li><strong>Contact Created</strong> (`contact.created`) — A new contact was created.</li>
          <li><strong>Contact Updated</strong> (`contact.updated`) — An existing contact was updated, including being archived.</li>
        </ul>
      </div>
    </Step>

    <Step title="Invoice events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for sales invoices and bills.</p>

        <ul>
          <li><strong>Invoice Created</strong> (`invoice.created`) — A new invoice or bill was created.</li>
          <li><strong>Invoice Updated</strong> (`invoice.updated`) — An existing invoice or bill was updated, including being approved, paid, voided or deleted.</li>
        </ul>
      </div>
    </Step>

    <Step title="Credit note events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for credit notes.</p>

        <ul>
          <li><strong>Credit Note Created</strong> (`creditnote.created`) — A new credit note was created.</li>
          <li><strong>Credit Note Updated</strong> (`creditnote.updated`) — An existing credit note was updated, including allocations, refunds and voids.</li>
        </ul>
      </div>
    </Step>

    <Step title="Prepayment and overpayment events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events for prepayments and overpayments.</p>

        <ul>
          <li><strong>Prepayment Created</strong> (`prepayment.created`) — A new prepayment was created.</li>
          <li><strong>Prepayment Updated</strong> (`prepayment.updated`) — An existing prepayment was updated, for example allocated, refunded or voided.</li>
          <li><strong>Overpayment Created</strong> (`overpayment.created`) — A new overpayment was created.</li>
          <li><strong>Overpayment Updated</strong> (`overpayment.updated`) — An existing overpayment was updated, for example allocated, refunded or voided.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Delivery format</h2>

  <p>Details of how Xero delivers events to StackOne.</p>

  <Steps>
    <Step title="Batched payloads">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Each request carries an `events` array and can contain several events of different categories. StackOne splits every request and routes each event on its own by its `eventCategory` and `eventType`. The event data is that single Xero event, with `resourceId`, `resourceUrl`, `eventDateUtc` and `tenantId`.</p>
      </div>
    </Step>

    <Step title="Signatures and retries">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Xero signs each request with a base64 HMAC SHA256 digest in the `x-xero-signature` header, keyed with the Webhooks key. StackOne verifies it during Intent to receive. Xero retries failed deliveries and disables the webhook after 24 hours of failures, which puts it back to 'Intent to receive' required.</p>
      </div>
    </Step>
  </Steps>
</section>

## Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.