Overview
Webhooks allow you to receive real-time notifications when events occur in your TribeMade store. When a customer successfully places an order, TribeMade automatically sends a POST request to all your configured webhook URLs with complete order details.No polling required! Webhooks push data to you automatically, saving API calls and providing instant notifications.
How Webhooks Work
Event Details
- Event:
order.created - When: Immediately after payment verification succeeds
- What: Complete order and customer details
- Method: POST request with JSON payload
- Recipients: All configured webhook URLs (up to 5)
Configure Webhooks
Step 1: Set Up Your Endpoint
Create an endpoint on your server to receive webhook notifications:Step 2: Add Webhook URL to Dashboard
- Log in to TribeMade Dashboard
- Navigate to Developer section
- Add your webhook URL (e.g.,
https://yourdomain.com/webhook/orders) - You can add up to 5 webhook URLs
Step 3: Test Your Webhook
Place a test order in your store to verify your webhook receives the notification.Webhook Payload
HTTP Request
Method:POSTContent-Type:
application/json
Payload Structure
Event type. Always
"order.created" for new orders.Unique order identifier (UUID)
Your store’s unique identifier (UUID)
Ordered product identifier (UUID)
Order status. Always
"started" for new orders.Order creation timestamp (ISO 8601 format, UTC)
Customer information
Order details
Example Payload
Webhook Requirements
Your Webhook Endpoint Must:
Accept POST requests
Accept POST requests
- Listen for POST method
- Parse JSON request body
- Handle
Content-Type: application/json
Return 2xx status code
Return 2xx status code
- Any status 200-299 is considered success
- Common:
200 OK,201 Created,202 Accepted - Return quickly (within 5 seconds)
Respond within 5 seconds
Respond within 5 seconds
- Timeout after 5 seconds
- Process asynchronously if needed
- Return response immediately, then process
Use HTTPS (required)
Use HTTPS (required)
- HTTP endpoints are not accepted
- Must have valid SSL certificate
- Self-signed certificates won’t work
Example Implementations
Complete Python Implementation
Complete Node.js Implementation
Security Best Practices
Always use HTTPS
Always use HTTPS
- Never use HTTP endpoints
- Ensure valid SSL certificate
- Self-signed certificates won’t work
- HTTPS protects customer data in transit
Validate data structure
Validate data structure
Always validate webhook payload before processing:
Store raw webhooks
Store raw webhooks
Save original webhook payload for debugging and audit trails:
Handle duplicates
Handle duplicates
Same webhook may be sent multiple times. Use order_id to prevent duplicate processing:
Monitor webhook health
Monitor webhook health
Track webhook delivery and processing:
- Success/failure rates
- Processing time
- Error patterns
- Alert on failures
Performance Best Practices
Return 200 quickly
Return 200 quickly
Process webhooks asynchronously to respond within 5 seconds:❌ Bad: Synchronous processing✅ Good: Asynchronous processing
Use queues for processing
Use queues for processing
Implement a queue system (RabbitMQ, Redis, Celery, BullMQ):
- Webhook returns 200 immediately
- Background workers process orders
- Handle high-volume periods
- Retry failed processing
Implement retry logic
Implement retry logic
Retry failed operations with exponential backoff:
Monitor processing time
Monitor processing time
Track how long webhook processing takes:
Troubleshooting
Common Issues
Endpoint returns 404/500
Endpoint returns 404/500
Cause: Endpoint not found or server errorFix:
- Verify URL is correct
- Check server is running
- Review server logs for errors
- Test endpoint with curl or Postman
Endpoint times out (>5 seconds)
Endpoint times out (>5 seconds)
Cause: Processing takes too longFix:
- Process asynchronously
- Return 200 immediately
- Use background queue
- Optimize database queries
Using HTTP instead of HTTPS
Using HTTP instead of HTTPS
Cause: Endpoint URL starts with http://Fix:
- Use HTTPS URL with valid SSL
- Get SSL certificate (Let’s Encrypt is free)
- Configure server for HTTPS
Invalid SSL certificate
Invalid SSL certificate
Cause: Expired or self-signed certificateFix:
- Use valid SSL from trusted CA
- Renew expired certificates
- Don’t use self-signed certificates
Webhook not received
Webhook not received
Causes:
- Endpoint not configured in dashboard
- Server is down or unreachable
- Firewall blocking requests
- Port not open
- Verify webhook URL in dashboard
- Check server status
- Configure firewall rules
- Ensure port is accessible
Testing Webhooks
Use webhook testing tools
Use webhook testing tools
Test your endpoint before going live:
- Webhook.site: https://webhook.site
- Get instant webhook URL
- Inspect raw requests
- No server setup needed
- RequestBin: https://requestbin.com
- Similar to webhook.site
- View request details
- ngrok: Expose local server to internet
Test with curl
Test with curl
Simulate webhook locally:
Place test order
Place test order
The most reliable test:
- Create test product in your store
- Place order as customer
- Verify webhook received
- Check all fields present
- Validate processing works
Webhook vs. Polling
Why Webhooks Are Better
| Aspect | Webhooks | Polling |
|---|---|---|
| Latency | Instant (< 1 second) | 1-5 minutes delay |
| API Calls | 0 calls needed | Hundreds/day |
| Server Load | Minimal | High |
| Rate Limits | Not affected | Quickly exceeded |
| Complexity | Low | Medium |
| Real-time | ✅ Yes | ❌ No |
Example: Cost Comparison
Scenario: 100 orders per day With Polling (every minute):- API calls per day: 1,440 (24 hours × 60 minutes)
- Most calls return no new orders
- Wastes API rate limit
- Delayed notifications
- API calls per day: 0
- Instant notifications
- No wasted calls
- Better customer experience

