Skip to main content

Update Webhook Settings

PATCH 
/api/xero/webhook-settings/:integrationInstanceId

Update a Xero connection's real-time sync settings. Send webhook_enabled, categories, or both — at least one of the two is required.

Not yet available to API tokens

This endpoint currently requires session authentication; Personal Access Token scope support is in progress.

Request body:

  • webhook_enabled (boolean, required without categories): turn event processing for this connection on or off. Turning it off leaves the connection authorised and keeps its event history; delivered events simply stop being acted on.
  • categories (object, required without webhook_enabled): per-category processing switches keyed by category — CONTACT, INVOICE, CREDITNOTE — each a boolean. May be partial: the keys you send are merged onto the connection's current switches, so switching one category off never clears another. Unrecognised keys are ignored, and switching on a category that is not in supported_categories has no effect.

The delivery URL and signing key belong to the shared Xero application and are platform-wide configuration — they cannot be set through this endpoint, and any such fields in the body are ignored.

Returns the full settings payload, identical in shape to Show Webhook Settings:

Response fields:

  • integration_instance_id (integer): the Xero connection these settings belong to.
  • webhook_enabled (boolean): whether this connection acts on the events Xero delivers. A connection that has never been toggled reads true.
  • categories (object): per-category processing switches, keyed by category — CONTACT, INVOICE, CREDITNOTE — each a boolean. Every known category is always present; a category that has never been toggled reads true, so a new connection processes everything until a type is switched off.
  • supported_categories (array of strings, read-only): the subset of categories SKU.io currently does something with. Switching on a category that is not in this list has no effect — its events are still recorded, but they are marked ignored and no data is fetched from Xero for them. Read this rather than assuming all three categories are live; the list grows as more inbound syncs ship.
  • ops.delivery_url (string, read-only): the single platform-wide URL Xero delivers every organisation's events to.
  • ops.signing_key_configured (boolean, read-only): whether the platform-wide signing key is in place.
  • ops.subscribed_topics (array of strings, read-only): the event categories the shared Xero application is subscribed to — what Xero sends, as opposed to supported_categories, which is what SKU.io acts on.
  • ops.events_last_24h (integer, read-only): events received for this connection in the last 24 hours.
  • ops.last_failure_at (ISO-8601 datetime or null, read-only) and ops.last_failure_message (string or null, read-only): when the connection's most recent event failed, and why. Both null when nothing has failed.

Path parameters:

  • integrationInstanceId (integer, required): Xero integration instance ID.

Errors:

  • 422 when neither webhook_enabled nor categories is sent, or when a category value is not a boolean.
  • 404 when the Xero connection does not exist.

Authentication: Bearer token.

Requires the integrations.update permission.

Request​

Responses​

OK

Response Headers
    Content-Type