How to Set Up Xero Webhooks: Quick Integration Guide

Quick answer

Xero webhooks provide real-time notifications when accounting data changes in your Xero organization. Setup requires registering an app in the Xero Developer Portal, configuring webhook subscriptions for specific events (invoices, contacts, etc.), and creating a publicly accessible HTTPS endpoint. 

Your endpoint must respond within 5 seconds with HTTP 200 OK and validate incoming requests using HMAC-SHA256 signature verification. Xero enforces rate limits of 5 concurrent calls, 60 calls per minute, and 5,000 calls per day. For no-code solutions, Coefficient offers instant webhook integration with Xero data in spreadsheets.

Prerequisites and requirements

Before setting up Xero webhooks, ensure you have the following foundational elements in place.

• Registered Xero app: Create an app in the Xero Developer Portal at developer.xero.com under “My Apps.” Your app must be connected to at least one Xero organization capable of generating webhook events.
• Webhook subscription configuration: Set up webhook subscriptions within the developer portal, specifying which event types your webhook should monitor. Options include contact changes, invoice updates, payment notifications, and other accounting events.
• Publicly accessible HTTPS endpoint: Xero requires SSL (port 443) for webhook delivery and won’t send notifications to localhost unless you use tunneling services like ngrok. Your endpoint must be reachable from Xero’s servers.
• Webhook signing key access: Obtain your webhook key from the developer portal. This key validates incoming requests from Xero by verifying the x-xero-signature header using HMAC-SHA256 encryption.
• Proper server response logic: Your endpoint must respond within 5 seconds with HTTP 200 OK for valid requests (no body or cookies). Invalid signatures must return HTTP 401 Unauthorized to maintain webhook functionality.

API limits and constraints

Xero enforces strict rate limits that directly impact webhook performance and integration reliability.

• Concurrent request limits: Maximum of 5 calls in progress simultaneously. Exceeding this limit triggers immediate rejections and 429 “Too Many Requests” errors.
• Per-minute restrictions: 60 calls per minute per connected organization, per app. Short-term bursts above this threshold receive 429 error responses and require retry logic implementation.
• Daily usage caps: 5,000 calls per day per organization, per app. This limit resets at midnight UTC and applies to all API interactions including webhook-triggered calls.
• Batch processing recommendations: Keep batch sizes to approximately 50 items for optimal performance. Larger batches may encounter processing delays or timeouts.
• High-volume considerations: Organizations using multiple Xero accounts face an overall minute limit of 10,000 calls across all accounts. Plan accordingly for multi-organization integrations.

Step-by-step Xero webhook setup

Follow this systematic approach to configure functional Xero webhooks for your integration.

Step 1: Create or select your Xero app

Navigate to the “My Apps” section in the Xero Developer portal and choose your existing app or create a new one for webhook functionality.

• Configure app settings: Ensure your app has appropriate scopes and permissions for the data you want to monitor. Webhook subscriptions require corresponding API access rights.
• Note your app credentials: Record your Client ID and Client Secret for authentication purposes. These credentials are essential for OAuth 2.0 flows and API access.
• Set up OAuth flows: Configure redirect URIs and authentication settings if your integration requires user consent for data access.

Step 2: Configure webhook subscription settings

Access your app settings and navigate to the “Webhooks” section to set up event monitoring.

Choose event categories: Select specific events you want to subscribe to, such as:

• Invoice creation, updates, or status changes
• Contact additions or modifications
• Payment notifications and bank transaction updates
• Purchase order changes
• Account and organization modifications

Enter endpoint URL: Provide your publicly accessible HTTPS endpoint URL where Xero will deliver webhook notifications. Ensure this URL can handle POST requests and process JSON payloads.

Configure retry settings: Xero automatically retries failed webhook deliveries. Understand the retry schedule to avoid processing duplicate events.

Step 3: Verify your endpoint with “Intent to Receive”

Xero sends a verification request to confirm your endpoint can properly handle webhook notifications.

Handle verification requests: Your endpoint must process the verification payload and respond appropriately:

javascript

Copy Code

// Example verification handler

app.post(‘/xero-webhook’, (req, res) => {

    const receivedSignature = req.headers[‘x-xero-signature’];

    const payload = JSON.stringify(req.body);

    const webhookKey = ‘YOUR_WEBHOOK_KEY_FROM_XERO’;

    

    // Generate HMAC signature

    const crypto = require(‘crypto’);

    const expectedSignature = crypto

        .createHmac(‘sha256’, webhookKey)

        .update(payload)

        .digest(‘base64’);

    

    // Verify signature

    if (receivedSignature === expectedSignature) {

        res.status(200).send(); // Valid signature

    } else {

        res.status(401).send(); // Invalid signature

    }

});

Respond within time limits: Ensure your endpoint responds within 5 seconds. Delayed responses cause verification failures and webhook disabling.

Process raw request body: Use the raw request body for signature verification, not parsed JSON. Many frameworks automatically parse JSON, breaking signature validation.

Step 4: Save configuration and obtain webhook key

After successful verification, save your webhook settings to activate event monitoring.

• Record webhook key: Xero generates a unique webhook key for your app. Store this key securely as it’s required for all future signature validations.
• Enable webhook subscriptions: Activate the specific event types you want to monitor. You can modify these subscriptions later as your integration needs evolve.
• Monitor webhook status: Use the developer portal to track webhook delivery success rates and identify any configuration issues.

Step 5: Test your webhook integration

Trigger test events in Xero to validate your webhook receives and processes notifications correctly.

• Create test events: Perform actions in your Xero organization that should trigger webhooks, such as creating invoices or adding contacts.
• Monitor delivery logs: Check your server logs and the Xero developer portal for webhook delivery confirmations and any error messages.
• Validate payload processing: Ensure your application correctly processes webhook payloads and performs the intended actions based on the received data.

Common integration issues

Real-world Xero webhook implementations encounter several recurring challenges that require careful attention.

“WebhookNotConfigured” errors and endpoint accessibility

• Incorrect URL configuration: Webhook URLs not properly set or publicly accessible due to firewall rules, DNS issues, or incorrect endpoint paths. Users notice changes in Xero don’t appear in their applications, causing data synchronization gaps.
• HTTPS protocol requirements: Servers unable to handle HTTPS traffic or respond using required secure protocols. According to developer documentation, Xero rejects HTTP endpoints and requires SSL encryption for all webhook deliveries.
• Connectivity validation failures: Common mistakes include typos in endpoint URLs, incorrect route handling, or firewalls blocking Xero’s webhook delivery servers. Tools like webhook.site or ngrok help identify connectivity issues during development.

Signature verification and “Intent to Receive” validation

• HMAC implementation complexity: Many developers struggle with Xero’s x-xero-signature header validation using HMAC-SHA256 encryption. Community discussions highlight confusion around base64 encoding, proper header comparison, and signature generation logic.
• Validation handshake failures: Incorrect status codes or response body content during the “Intent to Receive” process prevents Xero from enabling webhook delivery. Responses must be exactly HTTP 200 for valid signatures and HTTP 401 for invalid ones.
• Raw payload processing: Frameworks that automatically parse JSON break signature validation since HMAC calculation requires the raw request body. Developers must access unparsed request data for accurate signature verification.

Slow responses and retry loops during high server load

• Timeout cascade failures: Servers under high load that exceed Xero’s 5-second response requirement trigger retry loops. Stack Overflow discussions document cases where busy Apache servers delay webhook responses, creating cascading retry buildups.
• Retry storm amplification: Xero’s automatic retry logic can overwhelm already-stressed servers, creating exponentially increasing webhook queues that effectively break the integration until manually reset.
• Asynchronous processing solutions: Best practices include immediately logging and responding to webhooks, then processing payloads asynchronously. Switching from legacy server setups to lightweight Node.js or Go-based webhook receivers improves response times.

Hitting API and rate limits unexpectedly

• Downstream API call accumulation: Webhooks often trigger additional API calls to Xero or other systems, quickly exhausting the 60 calls per minute limit. Bulk updates or synchronized processes can breach daily limits unexpectedly.
• Rate limit monitoring gaps: Insufficient tracking of API usage leads to request failures and missed webhook events. Community recommendations stress monitoring x-rate-limit-remaining headers and implementing proactive alerts.
• Cascading failure prevention: Implement exponential backoff retry logic, queue management systems, and rate limit tracking to prevent webhook-triggered API calls from overwhelming Xero’s limits and breaking data synchronization.

No-code webhook workflows for Google Sheets or Excel

Transform your Xero data management with Coefficient’s seamless integration for Excel and Google Sheets. Skip complex webhook development and connect Xero directly to your spreadsheets.

Webhooks trigger live data pulls into Coefficient from any system you use. Your external systems tell Coefficient exactly when to refresh Xero data imports. Whether data changes in Xero, your spreadsheet reacts in real-time.

Instead of waiting for scheduled syncs or manual refreshes, keep dashboards and reports current the moment source data changes. Click the three dots on your import details and copy your webhook URL to get started.

How Coefficient’s Xero webhooks work

1. Import Xero data: Begin by importing data from Xero into your Google Sheet or Excel file using the Coefficient sidebar. Connect to invoices, contacts, payments, or any Xero accounting data.
2. Access import settings: In the Coefficient sidebar, locate your desired Xero import under the “Imports” section. This displays all active data connections in your spreadsheet.
3. Open the management menu: Click the three-dot menu icon next to your import’s name. This reveals additional configuration options for the data connection.
4. Select edit mode: From the dropdown menu, choose the “Edit” option. This opens the import configuration interface where you can modify connection settings.
5. Generate webhook URL: In the “Edit Import” screen, click the three-dot menu icon again. Look for the “Webhook URL” option in the expanded menu.
6. Configure refresh scope: Select “Webhook URL” to open the “Refresh with webhook” popup. Choose between refreshing only the specific import or all imports within the entire spreadsheet.
7. Implement in Xero systems: Paste the webhook URL into your Xero app webhook settings or third-party automation platforms. When Xero data changes, automatic refreshes occur in your spreadsheet.
8. Real-time synchronization: Your spreadsheets stay current with Xero changes without manual intervention, complex signature validation, or server maintenance requirements.

Custom development vs Coefficient comparison

Aspect	Custom Development	Coefficient.io
Setup Time	2-4 weeks	5 minutes
Development Cost	$5,000-$15,000	$29-$299/month
Maintenance	Ongoing dev resources	Fully managed
Security	Must implement yourself	Enterprise-grade built-in
Monitoring	Build your own	24/7 automated monitoring
Scaling	Handle infrastructure yourself	Auto-scaling included
Updates	Maintain API changes	Automatic updates

Automate your Xero workflows today

Xero webhooks enable powerful real-time accounting data synchronization when properly implemented. While requiring technical expertise for custom development, they provide immediate notification capabilities for critical business events.

Consider your team’s development capacity and maintenance requirements when choosing between custom webhook implementation and managed solutions. Both approaches eliminate manual data checking and improve financial process automation.

Ready to streamline your Xero data workflows? Get started with Coefficient and connect Xero to your spreadsheets without complex webhook development.

Frequently asked questions

Does Xero support webhooks?

Yes, Xero provides comprehensive webhook functionality through the Xero Developer Portal. You can subscribe to various events including invoice changes, contact updates, and payment notifications. However, setup requires technical implementation including HMAC signature validation and proper endpoint configuration.

How do I set up Xero webhooks?

Create an app in the Xero Developer Portal, configure webhook subscriptions for desired events, and provide a secure HTTPS endpoint URL. Your endpoint must validate HMAC-SHA256 signatures and respond within 5 seconds. Complete the “Intent to Receive” verification process to activate webhook delivery.

What are Xero webhook rate limits?

Xero enforces 5 concurrent calls, 60 calls per minute, and 5,000 calls per day per organization. Exceeding these limits results in 429 “Too Many Requests” errors. Monitor your API usage carefully, especially when webhooks trigger additional API calls to Xero or other systems.

How do I validate Xero webhook signatures?

Use HMAC-SHA256 encryption with your webhook key to generate a signature from the raw request body. Compare this with the x-xero-signature header value. Return HTTP 200 for matching signatures and HTTP 401 for invalid ones. Signature validation is required for webhook functionality.

Can I use Xero webhooks without coding?

While Xero webhooks require technical implementation, Coefficient provides a no-code solution for real-time Xero data integration with spreadsheets. This eliminates the need for custom webhook development, signature validation, and server maintenance while providing the same real-time data benefits.