Real-Time Event Notifications
Receive instant notifications when orders are fulfilled, shipped, or inventory levels change. Build reactive integrations with webhooks.
What are Webhooks?
Webhooks allow your application to receive real-time HTTP POST notifications when events occur in 3PL SHIP. Instead of polling our API for changes, we'll send data to your server instantly.
Real-Time
Receive events as they happen
Secure
Cryptographically signed payloads
Flexible
Subscribe to specific events
Available Events
Order Events
order.createdNew order received
order.fulfilledOrder picked and packed
order.shippedOrder handed to carrier
order.deliveredOrder delivered to customer
order.cancelledOrder was cancelled
Inventory Events
inventory.updatedInventory level changed
inventory.low_stockStock below threshold
Return Events
return.createdReturn request initiated
return.receivedReturn arrived at warehouse
Shipment Events
shipment.tracking_updatedNew tracking event
Setting Up Webhooks
Step 1: Create an Endpoint
First, create an HTTPS endpoint on your server to receive webhook events:
const express = require('express');
const crypto = require('crypto');
const app = express();
app.post('/webhooks/3plship', express.raw({type: 'application/json'}), (req, res) => {
const signature = req.headers['x-3plship-signature'];
const payload = req.body;
// Verify webhook signature
const expectedSignature = crypto
.createHmac('sha256', process.env.WEBHOOK_SECRET)
.update(payload)
.digest('hex');
if (signature !== expectedSignature) {
return res.status(401).send('Invalid signature');
}
// Parse and handle the event
const event = JSON.parse(payload);
switch(event.type) {
case 'order.shipped':
handleOrderShipped(event.data);
break;
case 'inventory.low_stock':
handleLowStock(event.data);
break;
// Handle other events...
}
res.status(200).send('Received');
});
app.listen(3000);Step 2: Register Your Webhook
Register your endpoint URL with 3PL SHIP:
curl -X POST https://api.3plship.com/v1/webhooks \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://yourdomain.com/webhooks/3plship",
"events": [
"order.shipped",
"order.delivered",
"inventory.low_stock"
]
}'Response:
{
"id": "wh_abc123",
"url": "https://yourdomain.com/webhooks/3plship",
"events": ["order.shipped", "order.delivered", "inventory.low_stock"],
"secret": "whsec_xyz789",
"created_at": "2025-01-15T10:30:00Z"
}Verifying Webhook Signatures
Always verify webhook signatures to ensure requests are from 3PL SHIP:
Signature Header
Every webhook includes an X-3plship-Signature header
HMAC SHA256
Signature is computed using HMAC SHA256 with your webhook secret
Constant-Time Comparison
Always use constant-time comparison to prevent timing attacks
Security Warning
Never process webhooks without verifying the signature first. This prevents attackers from sending fake events to your endpoint.
Testing Webhooks
Use our testing tools to ensure your webhook endpoint works correctly:
Send Test Event
curl -X POST https://api.3plship.com/v1/webhooks/wh_abc123/test \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"event": "order.shipped"
}'View Webhook Logs
Check delivery status and response codes in your dashboard or via API:
curl https://api.3plship.com/v1/webhooks/wh_abc123/logs \
-H "Authorization: Bearer YOUR_SECRET_KEY"Local Development with ngrok
For local testing, use ngrok to expose your development server:
# Start ngrok
ngrok http 3000
# Use the ngrok URL in your webhook configuration
# Example: https://abc123.ngrok.io/webhooks/3plshipBest Practices
Respond Quickly
Return a 200 status code within 5 seconds. Process heavy tasks asynchronously in a background job.
Handle Duplicate Events
Make your webhook handler idempotent. Use event IDs to track which events you've processed.
Monitor Failures
Set up alerts for webhook delivery failures. We'll retry failed webhooks up to 3 times with exponential backoff.
Use HTTPS
Webhook URLs must use HTTPS in production for security.
Ready to set up webhooks?