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:

1

Contact Integration Team

Provide your webhook URLs to the MasonHub integration team

2

Specify Event Types

Define which events you want to receive notifications for

3

Configure Authentication

Set up webhook signature verification secrets

4

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

Event: order.fulfilled

Use Case: Update ERP with shipment details

Action:

  • Update order status
  • Record tracking numbers
  • Trigger customer notifications

​
Inventory Events

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

1

Setup Test Endpoints

Configure webhook endpoints in your development environment

2

Register with MasonHub

Provide test webhook URLs to integration team

3

Trigger Test Events

Create test orders and shipments to generate webhook events

4

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.

Polling via GET CallsCommercial Invoice Requirements