​

Callback Configuration API

The Callbacks API manages webhook subscriptions for real-time event notifications from MasonHub. Register callback URLs to receive immediate notifications when events occur in the system, enabling responsive integrations and real-time data synchronization.

​

Core Operations

​

Get Callback URLs

Retrieve configured webhook subscriptions and their status information.

​

Query Parameters

​

Create Callback URLs

Register webhook endpoints for real-time event notifications.

“message_type”: “orderEvent”, “status”: “active” } ] }

</CodeGroup>

### Delete Callback URLs

```http
DELETE /callbacks
Authorization: Bearer your_jwt_token
Content-Type: application/json

[
  "callback-uuid-123",
  "callback-uuid-456"
]

​

Available Event Types

​

Security & Authentication

​

HTTPS Requirement

​

Verification Tokens

Enhance security with verification tokens:

• Token Configuration
• Token Verification

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

​

Request Headers

MasonHub callback requests include identifying headers:

POST /your-webhook-endpoint
User-Agent: MasonHub-Webhook/1.0
Content-Type: application/json
X-MasonHub-Event: orderEvent
X-MasonHub-Delivery: uuid-delivery-id

​

Callback Payload Format

All callbacks use a consistent structure:

​

Delivery Guarantees

​

Reliability Features

​

Response Requirements

Your webhook endpoints must:

​

Callback Management

​

Callback Holds

Temporarily suspend callback delivery when needed:

• Get Holds
• Create Holds
• Remove Holds

GET /callback_holds
Authorization: Bearer your_jwt_token

​

Use Cases for Holds

​

Implementation Examples

​

Python Flask Webhook

​

Node.js Express Webhook

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

// Middleware for webhook verification
function verifyWebhook(req, res, next) {
  const token = req.body.token;
  const expectedToken = process.env.MASONHUB_TOKEN;
  
  if (expectedToken && token !== expectedToken) {
    return res.status(401).send('Unauthorized');
  }
  
  next();
}

// Idempotency tracking
const processedMessages = new Set();

app.post('/webhook/masonhub', verifyWebhook, async (req, res) => {
  try {
    const { message_type, message_id, data } = req.body;
    
    // Check for duplicate
    if (processedMessages.has(message_id)) {
      return res.status(200).send('Already processed');
    }
    
    // Mark as processed
    processedMessages.add(message_id);
    
    // Process based on message type
    switch (message_type) {
      case 'skuInventoryChange':
        await handleInventoryChange(data);
        break;
      case 'orderEvent':
        await handleOrderEvent(data);
        break;
      default:
        console.warn(`Unknown message type: ${message_type}`);
    }
    
    res.status(200).send('OK');
    
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).send('Error');
  }
});

​

Testing & Development

​

Sandbox Environment

Test callbacks in the sandbox environment:

​

Development Tools

• ngrok for Local Testing
• Webhook Testing Service

# Install ngrok
npm install -g ngrok

# Expose local server
ngrok http 3000

# Use the HTTPS URL for callback registration
# https://abc123.ngrok.io/webhook/masonhub

​

Monitoring & Troubleshooting

​

Common Issues

​

Monitoring Best Practices

​

Best Practices

​

Security

1. Use HTTPS Only: Never accept HTTP callback URLs
2. Verify Tokens: Implement token verification for all callbacks
3. Rate Limiting: Implement rate limiting on webhook endpoints
4. Input Validation: Validate all incoming webhook data

​

Performance

1. Quick Response: Return HTTP 200 within 30 seconds
2. Async Processing: Queue heavy processing for background workers
3. Idempotency: Handle duplicate events using message_id
4. Error Handling: Return appropriate HTTP status codes

​

Reliability

1. Monitoring: Implement comprehensive webhook monitoring
2. Alerting: Set up alerts for webhook failures
3. Logging: Log all webhook events for troubleshooting
4. Testing: Regularly test webhook endpoints

​

Next Steps

After implementing callback configuration, explore:

• Order Management for order event handling
• Inventory Management for inventory change events
• Authentication for secure API access