Webhooks - Smartbills

Overview

Webhooks allow you to receive HTTP notifications when specific events occur in your Smartbills account. Instead of polling the API for changes, Smartbills pushes notifications to your server in real-time.

Real-time updates: Webhooks are delivered within seconds of the event occurring, making them ideal for automation and integrations.

How Webhooks Work

Event Occurs

An action happens in Smartbills (e.g., expense created, report approved)

Webhook Triggered

Smartbills prepares a webhook payload with event details

HTTP POST Sent

Smartbills sends an HTTP POST request to your configured endpoint

Your Server Responds

Your server processes the webhook and returns a 200 OK response

Setting Up Webhooks

Register Your Webhook

curl --request POST \
  --url https://api.smartbills.io/v1/webhooks \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'x-tenant-id: 123' \
  --data '{
    "url": "https://your-domain.com/webhooks/smartbills",
    "events": ["expense.created", "expense_report.approved"],
    "description": "Production webhook endpoint"
  }'

import { SmartbillsClient } from '@smartbills/sdk';

const client = new SmartbillsClient({
  accessToken: 'YOUR_API_KEY',
  businessId: 123
});

const webhook = await client.webhooks.create({
  url: 'https://your-domain.com/webhooks/smartbills',
  events: ['expense.created', 'expense_report.approved'],
  description: 'Production webhook endpoint'
});

console.log('Webhook ID:', webhook.id);
console.log('Webhook Secret:', webhook.secret);

from smartbills import SmartbillsClient

client = SmartbillsClient(access_token="YOUR_API_KEY", business_id=123)

webhook = client.webhooks.create(
    url="https://your-domain.com/webhooks/smartbills",
    events=["expense.created", "expense_report.approved"],
    description="Production webhook endpoint"
)

print(f"Webhook ID: {webhook.id}")
print(f"Webhook Secret: {webhook.secret}")

Response

{
  "id": "wh_1234567890",
  "url": "https://your-domain.com/webhooks/smartbills",
  "events": ["expense.created", "expense_report.approved"],
  "description": "Production webhook endpoint",
  "secret": "whsec_abcdef123456",
  "status": "active",
  "createdAt": "2025-01-15T10:30:00Z"
}

Save the secret: The webhook secret is only shown once. Store it securely, you need it to verify webhook signatures.

Available Events

Expense Events

Event	Description
`expense.created`	A new expense has been uploaded or created
`expense.updated`	An existing expense has been modified
`expense.deleted`	An expense has been removed
`expense.categorized`	An expense category has been changed

Expense Report Events

Event	Description
`expense_report.submitted`	A report has been submitted for approval
`expense_report.approved`	A report has been approved by a manager
`expense_report.rejected`	A report has been rejected by an approver
`expense_report.recalled`	A report has been recalled by the submitter
`expense_report.comment_added`	A comment has been added to a report

Bill Events

Event	Description
`bill.created`	A new bill has been created
`bill.updated`	An existing bill has been modified
`bill.paid`	A bill has been marked as paid

Business Events

Event	Description
`business.updated`	Business settings have been modified
`business.user_added`	A user has been invited to a business
`business.user_removed`	A user has been removed from a business

Webhook Payload Structure

All webhooks follow this structure:

{
  "id": "evt_1234567890",
  "type": "expense.created",
  "createdAt": "2025-01-15T10:30:00Z",
  "data": {
    "expense": {
      "id": 12345,
      "amount": 49.99,
      "currency": "CAD",
      "merchant": "Office Depot",
      "date": "2025-01-15",
      "category": "Office Supplies",
      "status": "pending"
    }
  },
  "metadata": {
    "businessId": 123,
    "userId": 500
  }
}

Payload Fields

Field	Type	Description
`id`	string	Unique event identifier
`type`	string	Event type (e.g., `expense.created`)
`createdAt`	string	ISO 8601 timestamp of the event
`data`	object	Event-specific data payload
`metadata`	object	Business and user context

Webhook Security

Verify Signatures

Always verify webhook signatures to ensure requests are from Smartbills. Smartbills signs every webhook payload using HMAC-SHA256 with your webhook secret:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(JSON.stringify(payload)).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

// In your webhook handler:
app.post('/webhooks/smartbills', express.json(), (req, res) => {
  const signature = req.headers['x-smartbills-signature'];

  if (!verifyWebhookSignature(req.body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event
  const event = req.body;
  console.log('Received event:', event.type);

  res.status(200).send('OK');
});

import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)

def verify_webhook_signature(payload, signature, secret):
    computed = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(computed, signature)

@app.route('/webhooks/smartbills', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Smartbills-Signature')

    if not verify_webhook_signature(
        request.data.decode(),
        signature,
        os.environ['WEBHOOK_SECRET']
    ):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.json
    print(f"Received event: {event['type']}")

    return jsonify({'status': 'success'}), 200

Retry Policy

Smartbills automatically retries failed webhook deliveries:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	15 minutes
4th retry	1 hour
5th retry	6 hours
Final retry	24 hours

Retry conditions:

HTTP status code >= 500
Connection timeout
Connection refused
DNS resolution failure

No retry for:

HTTP status code < 500 (including 4xx errors)
Invalid SSL certificate

Return 200 OK: Always return a 200 status code when you successfully receive the webhook, even if processing fails. Handle processing errors internally to avoid unnecessary retries.

Managing Webhooks

List Webhooks

curl --request GET \
  --url https://api.smartbills.io/v1/webhooks \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'x-tenant-id: 123'

const webhooks = await client.webhooks.list();

webhooks = client.webhooks.list()

Update Webhook

curl --request PATCH \
  --url https://api.smartbills.io/v1/webhooks/wh_1234567890 \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'x-tenant-id: 123' \
  --data '{
    "events": ["expense.created", "expense.updated", "expense_report.approved"]
  }'

await client.webhooks.update('wh_1234567890', {
  events: ['expense.created', 'expense.updated', 'expense_report.approved']
});

client.webhooks.update("wh_1234567890",
    events=["expense.created", "expense.updated", "expense_report.approved"]
)

Delete Webhook

curl --request DELETE \
  --url https://api.smartbills.io/v1/webhooks/wh_1234567890 \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'x-tenant-id: 123'

await client.webhooks.delete('wh_1234567890');

client.webhooks.delete("wh_1234567890")

Test Webhook

Send a test event to verify your endpoint is working:

curl --request POST \
  --url https://api.smartbills.io/v1/webhooks/wh_1234567890/test \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'x-tenant-id: 123'

await client.webhooks.test('wh_1234567890');

client.webhooks.test("wh_1234567890")

Best Practices

Respond Quickly

Return a 200 OK response within 5 seconds. Acknowledge receipt immediately and process the event asynchronously using a job queue.

Handle Idempotency

Webhooks may be delivered more than once. Store event IDs and check for duplicates before processing.

Verify Signatures

Always verify the x-smartbills-signature header before processing any webhook payload.

Use HTTPS

Your webhook endpoint must use HTTPS in production to protect the payload in transit.

Log Everything

Log incoming webhook payloads, signature verification results, and processing outcomes for debugging.

Testing Webhooks Locally

Use tools like ngrok to test webhooks during local development:

# Start your local server
node server.js  # Running on http://localhost:3000

# Create a tunnel
ngrok http 3000
# Forwarding https://abc123.ngrok.io -> http://localhost:3000

# Register the ngrok URL as your webhook endpoint

API Keys

Secure your webhook endpoints

Error Handling

Handle webhook errors

Rate Limits

API rate limiting

Environments

Sandbox and production

​Overview

​How Webhooks Work

Overview

How Webhooks Work