- Getting data back into the ERP / Source System
- Callback Events (Webhooks)
Getting data back into the ERP / Source System
Callback Events (Webhooks)
Receive real-time notifications from MasonHub via webhook callbacks
Callback events (webhooks) provide real-time notifications when specific events occur in MasonHub. This approach delivers immediate updates to your ERP system without the need for continuous polling.
​Overview
Webhooks allow MasonHub to automatically call your endpoints when important events happen, such as order status changes, shipment updates, or inventory modifications.
Advantages
- Real-time notifications
- Reduced API call volume
- Immediate event processing
- Lower latency for critical updates
Considerations
- Requires publicly accessible endpoints
- Need proper security implementation
- Must handle retry logic
- Firewall configuration may be needed
​Supported Callback Events
​Order Events
​Inbound Shipment Events
​Webhook Setup Process
​1. Endpoint Development
Create secure endpoints in your system to receive webhook calls:
from flask import Flask, request, jsonify
import hmac
import hashlib
app = Flask(__name__)
@app.route('/webhooks/masonhub/orders', methods=['POST'])
def handle_order_webhook():
# Verify webhook signature
if not verify_webhook_signature(request):
return jsonify({'error': 'Invalid signature'}), 401
# Process the event
event_data = request.json
process_order_event(event_data)
return jsonify({'status': 'received'}), 200
def verify_webhook_signature(request):
signature = request.headers.get('X-MasonHub-Signature')
payload = request.get_data()
expected_signature = hmac.new(
WEBHOOK_SECRET.encode(),
payload,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected_signature)
​2. Webhook Registration
Register your webhook endpoints with MasonHub:
Contact Integration Team
Provide your webhook URLs to the MasonHub integration team
Specify Event Types
Define which events you want to receive notifications for
Configure Authentication
Set up webhook signature verification secrets
Test Configuration
Validate webhook delivery in sandbox environment
​Security Implementation
​Webhook Authentication
Always verify webhook authenticity to prevent unauthorized access to your systems.
​Signature Verification
MasonHub signs webhooks using HMAC-SHA256:
import hmac
import hashlib
def verify_signature(payload, signature, secret):
expected_signature = hmac.new(
secret.encode('utf-8'),
payload,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(
f"sha256={expected_signature}",
signature
)
​IP Allowlisting
Consider restricting webhook access to MasonHub IP addresses:
ALLOWED_IPS = [
'192.168.1.100', # Example MasonHub IP
'10.0.0.50' # Example MasonHub IP
]
def is_allowed_ip(request_ip):
return request_ip in ALLOWED_IPS
​Event Processing Patterns
​Idempotent Processing
Handle duplicate webhook deliveries gracefully:
def process_order_event(event_data):
event_id = event_data.get('event_id')
# Check if we've already processed this event
if is_event_processed(event_id):
return {'status': 'already_processed'}
# Process the event
result = update_order_in_erp(event_data)
# Mark event as processed
mark_event_processed(event_id)
return result
​Error Handling & Retries
​Asynchronous Processing
For complex processing, consider queuing webhook events:
import redis
import json
redis_client = redis.Redis()
@app.route('/webhooks/masonhub/orders', methods=['POST'])
def handle_order_webhook():
# Quickly acknowledge receipt
event_data = request.json
# Queue for processing
redis_client.lpush(
'webhook_queue',
json.dumps(event_data)
)
return jsonify({'status': 'queued'}), 200
# Separate worker process
def process_webhook_queue():
while True:
event_json = redis_client.brpop('webhook_queue')[1]
event_data = json.loads(event_json)
process_order_event(event_data)
​Event Types & Use Cases
​Order Events
Order Fulfillment
Order Updates
Event: order.fulfilled
Use Case: Update ERP with shipment details
Action:
- Update order status
- Record tracking numbers
- Trigger customer notifications
​Inventory Events
Stock Updates
Receipts
Event: inventory.updated
Use Case: Real-time inventory sync
Action:
- Update available quantities
- Trigger reorder alerts
- Update product availability
​Monitoring & Troubleshooting
​Webhook Health Monitoring
Delivery Metrics
- Successful deliveries
- Failed deliveries
- Average response times
- Retry rates
Processing Metrics
- Events processed
- Processing errors
- Queue depths
- Duplicate events
​Common Issues & Solutions
​Testing Webhooks
​Sandbox Testing
Setup Test Endpoints
Configure webhook endpoints in your development environment
Register with MasonHub
Provide test webhook URLs to integration team
Trigger Test Events
Create test orders and shipments to generate webhook events
Validate Processing
Confirm events are received and processed correctly
​Testing Tools
Use tools to test webhook handling:
# Using ngrok for local testing
ngrok http 8000
# Using curl to simulate webhook
curl -X POST http://localhost:8000/webhooks/masonhub/orders \
-H "Content-Type: application/json" \
-H "X-MasonHub-Signature: sha256=..." \
-d '{"event_type": "order.shipped", "order_id": "test"}'
​Round-Trip Validation
Critical Requirement: Ensure tracking numbers and shipment information successfully flow back to your source system through webhook processing.
​Validation Checklist
- Webhook endpoint receives events
- Signature verification works
- Events are processed correctly
- ERP system is updated
- Customer notifications are triggered
- Error handling works properly
​Complete Documentation
Callback Events Documentation
Comprehensive documentation for setup instructions and payload samples
​Next Steps
Consider implementing a hybrid approach using both polling for bulk data and webhooks for real-time critical updates.