Skip to main content

Overview

Webhooks allow you to receive HTTP notifications when specific events occur in your Smartbills account. Instead of polling the API for changes, Smartbills will push 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

1

Event Occurs

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

Webhook Triggered

Smartbills prepares a webhook payload with event details
3

HTTP POST Sent

Smartbills sends an HTTP POST request to your configured endpoint
4

Your Server Responds

Your server processes the webhook and returns a 200 OK response
5

Confirmation

Smartbills marks the webhook as delivered

Setting Up Webhooks

Create a Webhook Endpoint

First, create an endpoint on your server to receive webhooks:

Register Your Webhook

Register your endpoint with Smartbills:

Response

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

Available Events

Expense Events

Expense Report Events

Business Events

User Events

Webhook Payload Structure

All webhooks follow this structure:

Example Payloads

Webhook Security

Verify Signatures

Always verify webhook signatures to ensure requests are from Smartbills:

Security Best Practices

1

Always Verify Signatures

Never process webhooks without verifying the signature first
2

Use HTTPS

Your webhook endpoint must use HTTPS in production
3

Keep Secrets Secure

Store webhook secrets in environment variables, never in code
4

Validate Payload

Check that the payload structure matches expected format
5

Use IP Allowlist (Optional)

Restrict webhook requests to Smartbills IP addresses

Handling Webhooks

Best Practices

Return a 200 OK response within 5 secondsDo:
  • Acknowledge receipt immediately
  • Process asynchronously
  • Use job queues for heavy processing
Don’t:
  • Perform long-running operations
  • Make external API calls before responding
  • Wait for database writes to complete
Webhooks may be delivered more than onceStrategy:
  • Store event IDs
  • Check if event was already processed
  • Skip duplicate events
Handle failures gracefullyIf processing fails:
  • Log the error
  • Store webhook for retry
  • Implement exponential backoff
  • Alert on repeated failures
Maintain detailed logs for debuggingLog:
  • Incoming webhook payloads
  • Signature verification results
  • Processing outcomes
  • Errors and exceptions

Webhook Retries

Automatic Retries

Smartbills automatically retries failed webhooks: 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
  • Signature verification failures
Return 200 OK: Always return a 200 status code if you successfully received the webhook, even if processing fails. Handle processing errors internally.

Managing Webhooks

List Webhooks

Update Webhook

Delete Webhook

Test Webhook

Send a test event to your endpoint:

Webhook Logs

View delivery history and debug issues:
Response:

Testing Webhooks

Local Development

Use tools like ngrok to test webhooks locally:
1

Install ngrok

2

Start Your Server

3

Create Tunnel

4

Register Webhook

Use the ngrok URL as your webhook endpoint:
5

Test

Trigger events in Smartbills and watch your local server receive webhooks

Testing Tools

Webhook.site RequestBin

Troubleshooting

Check these:
  1. Endpoint is accessible
    • Test with curl or Postman
    • Ensure HTTPS is working
    • Check firewall rules
  2. Webhook is active
    • Verify status in dashboard
    • Check if webhook was disabled
  3. Events are subscribed
    • Confirm you’re subscribed to the event type
    • Check event filters
  4. No errors in logs
    • Review webhook delivery logs
    • Check for 4xx/5xx errors
Common causes:
  1. Wrong secret
    • Verify you’re using the correct webhook secret
    • Check environment variables
  2. Payload modification
    • Don’t modify the raw payload before verification
    • Use the exact bytes received
  3. Encoding issues
    • Ensure consistent encoding (UTF-8)
    • Don’t parse JSON before verification
Debug:
This is normal behaviorWebhooks may be delivered more than once due to:
  • Network issues
  • Timeout retries
  • Server restarts
Solution: Implement idempotency
Problem: Webhooks failing due to timeoutSolution: Process asynchronously

Example Use Cases

Sync to Accounting Software

Send Slack Notifications

Trigger Reimbursement

Next Steps

API Keys

Secure your webhook endpoints

Rate Limits

Understand API rate limiting

Error Handling

Handle webhook errors

API Reference

Explore all API endpoints

Need Help?