MasonHub ERP Integration home pagelight logo
  1. Callbacks
  2. Create Callback URLs
POST
/callbacks
curl --request POST \
     --url https://sandbox.masonhub.co/dragonfly-cosmetics-demo/api/v1/callbacks \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/json' \
     --data '{
  "url": "<string>",
  "message_type": "<string>",
  "api_version": "1.0",
  "token": "<string>"
}'

Register webhook URLs to receive real-time event notifications from MasonHub. Subscribe to multiple event types by creating separate callbacks for each.

All callback URLs must use HTTPS. HTTP URLs will be rejected for security reasons.

​
Request Body

Send an array of callback objects to register. Each callback object supports:

url
required
string

HTTPS endpoint URL that will receive webhook notifications. Must be publicly accessible.

message_type
required
string

Event type to subscribe to. See available message types below.

api_version
default:1.0
string

API version for callback payloads. Defaults to “1.0”.

token
string

Optional verification token to include in callback requests for authentication. Recommended for production.

​
Available Message Types

curl -X POST "https://app.masonhub.co/{account}/api/v1/callbacks" \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "url": "https://api.clienturl.com/api/skuInventoryChange",
      "message_type": "skuInventoryChange",
      "api_version": "1.0",
      "token": "your_secure_verification_token"
    },
    {
      "url": "https://api.clienturl.com/api/orderEvent",
      "message_type": "orderEvent",
      "api_version": "1.0",
      "token": "your_secure_verification_token"
    }
  ]'

{
  "callbacks": [
    {
      "id": "callback-uuid-789",
      "url": "https://api.clienturl.com/api/skuInventoryChange",
      "message_type": "skuInventoryChange",
      "api_version": "1.0",
      "status": "active"
    },
    {
      "id": "callback-uuid-012",
      "url": "https://api.clienturl.com/api/orderEvent",
      "message_type": "orderEvent",
      "api_version": "1.0",
      "status": "active"
    }
  ]
}

​
Security

​
HTTPS Requirement

All callback URLs must use HTTPS for secure transmission:

{
  "url": "https://api.clienturl.com/webhook"
}

​
Verification Tokens

Include tokens for authenticating callback requests:

{
  "url": "https://api.clienturl.com/webhook",
  "message_type": "orderEvent",
  "token": "your_encrypted_verification_token"
}

The token will be included in all callback requests. Your endpoint should verify the token matches before processing events.

​
Webhook Endpoint Requirements

Your webhook endpoints must meet these requirements:

1

Accept POST Requests

All callbacks use the POST method with JSON payloads

2

Return HTTP 200

Respond with 200 status code to indicate successful processing

3

Respond Quickly

Return response within 30 seconds to prevent timeouts

4

Handle Duplicates

Implement idempotency using message_id to handle at-least-once delivery

5

Validate Authenticity

Verify token when configured to ensure requests are from MasonHub

​
Example Webhook Implementation

from flask import Flask, request, jsonify
import logging

app = Flask(__name__)
logger = logging.getLogger(__name__)

EXPECTED_TOKEN = "your_secure_verification_token"

@app.route('/webhook/masonhub', methods=['POST'])
def handle_masonhub_webhook():
    try:
        payload = request.get_json()

        # Verify token if configured
        if payload.get('token') != EXPECTED_TOKEN:
            logger.warning("Invalid token received")
            return jsonify({"error": "Unauthorized"}), 401

        message_type = payload['message_type']
        message_id = payload['message_id']
        data = payload['data']

        # Check for duplicate (implement your own logic)
        if is_duplicate(message_id):
            logger.info(f"Duplicate message {message_id} ignored")
            return jsonify({"status": "ok"}), 200

        # Process based on message type
        if message_type == 'skuInventoryChange':
            handle_inventory_change(data)
        elif message_type == 'orderEvent':
            handle_order_event(data)
        else:
            logger.warning(f"Unknown message type: {message_type}")

        return jsonify({"status": "ok"}), 200

    except Exception as e:
        logger.error(f"Webhook error: {e}")
        return jsonify({"error": str(e)}), 500

​
Delivery Guarantees

At-Least-Once Delivery

Events may be delivered multiple times. Implement idempotency using message_id.

Retry Logic

Failed deliveries are retried with exponential backoff up to 24 hours.

Timeout Handling

Requests timeout after 30 seconds. Respond quickly to avoid retries.

Error Logging

Delivery failures are logged and available on request for troubleshooting.

​
Testing

​
Sandbox Environment

Test callbacks in the sandbox environment:

https://sandbox.masonhub.co/{account}/api/v1/callbacks
  • All message types available
  • Use DataFactory to trigger test events
  • No impact on production data

​
Best Practices

Use Tokens

Always configure verification tokens for production endpoints.

Implement Idempotency

Store message_id to detect and ignore duplicate deliveries.

Log Everything

Log all callback events for debugging and audit trails.

Monitor Endpoints

Monitor webhook endpoint availability and response times.

Handle Errors Gracefully

Return appropriate HTTP status codes and log errors for investigation.

Store Callback IDs

Save the returned id for each callback for future deletion operations.

Start with a single callback type during testing, then expand to additional event types once your implementation is stable.