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
Available Events
Expense Events
Expense Report Events
Business Events
User Events
Webhook Payload Structure
All webhooks follow this structure:Example Payloads
- expense.created
- report.approved
- report.submitted
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
Respond Quickly
Respond Quickly
Return a
200 OK response within 5 secondsDo:- Acknowledge receipt immediately
- Process asynchronously
- Use job queues for heavy processing
- Perform long-running operations
- Make external API calls before responding
- Wait for database writes to complete
Handle Idempotency
Handle Idempotency
Webhooks may be delivered more than onceStrategy:
- Store event IDs
- Check if event was already processed
- Skip duplicate events
Implement Retry Logic
Implement Retry Logic
Handle failures gracefullyIf processing fails:
- Log the error
- Store webhook for retry
- Implement exponential backoff
- Alert on repeated failures
Log Everything
Log Everything
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
- HTTP status code < 500 (including 4xx errors)
- Invalid SSL certificate
- Signature verification failures
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: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- Free webhook testing tool
- Inspect webhook payloads
- No coding required
- URL: https://webhook.site
- Collect and inspect webhooks
- Debug payload structure
- URL: https://requestbin.com
Troubleshooting
Webhooks not being delivered
Webhooks not being delivered
Check these:
-
Endpoint is accessible
- Test with curl or Postman
- Ensure HTTPS is working
- Check firewall rules
-
Webhook is active
- Verify status in dashboard
- Check if webhook was disabled
-
Events are subscribed
- Confirm you’re subscribed to the event type
- Check event filters
-
No errors in logs
- Review webhook delivery logs
- Check for 4xx/5xx errors
Signature verification fails
Signature verification fails
Common causes:
-
Wrong secret
- Verify you’re using the correct webhook secret
- Check environment variables
-
Payload modification
- Don’t modify the raw payload before verification
- Use the exact bytes received
-
Encoding issues
- Ensure consistent encoding (UTF-8)
- Don’t parse JSON before verification
Duplicate webhooks
Duplicate webhooks
This is normal behaviorWebhooks may be delivered more than once due to:
- Network issues
- Timeout retries
- Server restarts
Webhook endpoint timing out
Webhook endpoint timing out
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?
- Webhook Issues: [email protected]
- Community: community.smartbills.io
- Status: status.smartbills.io