MasonHub ERP Integration home pagelight logo
  1. Callback Holds
  2. Create Callback Holds
POST
/callback_holds
curl --request POST \
     --url https://sandbox.masonhub.co/dragonfly-cosmetics-demo/api/v1/callback_holds \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/json' \
     --data '{
  "message_types": "<value>"
}'

Create callback holds to temporarily suspend delivery of specific message types to your webhook endpoints. This is useful during maintenance windows, system upgrades, or debugging.

Events that occur while holds are active will not be queued for later delivery. Once you remove the hold, only new events will be delivered.

​
Request Body

The request body accepts an array of message type strings to place on hold.

message_types
required
string[]

Array of message types to place on hold. Common types include:

  • skuInventoryChange - Inventory level changes
  • orderEvent - Order status and lifecycle events
  • shipmentEvent - Shipment tracking updates
  • inboundReceived - Inbound shipment receipts
curl -X POST "https://app.masonhub.co/{account}/api/v1/callback_holds" \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '[
    "skuInventoryChange",
    "orderEvent"
  ]'

{
  "status": "success",
  "holds_created": [
    "skuInventoryChange",
    "orderEvent"
  ],
  "total_holds": 2
}

​
Response Fields

status
string

Status of the operation. Returns success when holds are created.

holds_created
string[]

Array of message types that were successfully placed on hold.

total_holds
number

Total number of active holds after this operation.

​
Behavior

​
Idempotent Operations

If you create a hold for a message type that’s already on hold, the API will acknowledge it without error but won’t create a duplicate.

​
Multiple Message Types

You can place holds on multiple message types in a single request. The API processes them atomically - either all succeed or none are created.

​
Event Impact

Events that occur during a hold period are not delivered and not queued. They are effectively skipped. Plan your hold periods accordingly.

​
Use Cases

Scheduled Maintenance

Place holds before planned maintenance windows to prevent failed delivery attempts.

System Deployment

Suspend events during application deployments to avoid processing errors.

Load Testing

Control event flow during load testing or performance tuning.

Emergency Response

Quickly suspend events when detecting issues with your webhook processing.

​
Best Practices

1

Plan Hold Windows

Schedule holds during low-activity periods when possible to minimize lost events.

2

Document Hold Periods

Keep records of when holds are active for troubleshooting and auditing.

3

Test in Sandbox

Test callback hold behavior in sandbox environment before using in production.

4

Remove Promptly

Remove holds as soon as maintenance is complete to resume event delivery.

Remember to remove holds using the Delete Callback Holds endpoint when you’re ready to resume event delivery.

​
Example Workflow

# Place holds before maintenance
hold_types = ["skuInventoryChange", "orderEvent"]
requests.post(
    f"{base_url}/callback_holds",
    headers=headers,
    json=hold_types
)

# Perform maintenance tasks
perform_system_maintenance()

# Remove holds after maintenance
requests.delete(
    f"{base_url}/callback_holds",
    headers=headers,
    json=hold_types
)