Webhooks

Webhooks allow ShipEdge to automatically send notifications to your external systems when specific events occur, such as when an order is shipped, inventory is corrected, or a replenishment is received. This enables real-time integration without polling the API.

Why Use Webhooks?

Real-Time Updates

Receive instant notifications when events occur instead of checking the API repeatedly.

Automate Workflows

Trigger actions in your systems automatically when orders ship, inventory changes, or replenishments arrive.

Reduce API Calls

Eliminate the need to poll the API constantly. Webhooks push data to you only when events happen.

Stay Synchronized

Keep your external systems synchronized with ShipEdge automatically, reducing manual work and errors.

How Webhooks Work

Configure Webhook: Set up a webhook URL and select which events to monitor
Event Occurs: When the selected event happens (e.g., order ships), ShipEdge prepares the data
HTTP POST: ShipEdge sends an HTTP POST request to your webhook URL with event data
Your System Responds: Your server receives the data and processes it (update database, send email, etc.)
Confirmation: Your server responds with HTTP 200 to confirm receipt

Accessing Webhook Configuration

OMS (Order Management System)

Log in to your ShipEdge OMS account

Access your Order Management System account through the web interface.
Navigate to Preferences

Go to My Account > Preferences in the main menu.
Open Webhooks tab

Click on the Webhooks tab in Preferences.
Configure webhooks

You’ll see options to:
- Add new webhooks
- View existing webhooks
- View webhook logs
- Resend failed webhooks

WMS (Warehouse Management System)

WMS webhooks are configured separately and are available for warehouse-specific events.

Available Webhook Events

Order Events

Order Status Changes:

Order any status change - Triggers on any order status change (configurable)
Order pending - When order enters pending status
Order processing - When order moves to processing status
Order shipped - When order is shipped
Order canceled - When order is canceled
Order backorder - When order becomes backordered
Order divided - When order is divided into multiple shipments
Order updated by OMS - When order is updated through OMS

Order Shipping Methods:

Order shipped with shipping method - Filtered by specific shipping method
Order shipped by store - Filtered by store/channel
Order shipped by order type - Filtered by order type

Order Fulfillment Types:

Order shipped by Amazon FBA - When fulfilled by Amazon FBA
Order shipped by Amazon MCF - When fulfilled by Amazon MCF
Order shipped by dropshipper - When fulfilled by dropshipper
Order shipped by Shipedge - When fulfilled by ShipEdge warehouse
Order shipped by WFS - When fulfilled by WFS

Order Actions:

Order shipped items - When specific items are shipped
Order pending items - When specific items are pending
Order dropship cancel - When dropship order is canceled
Order refund - When order is refunded
Order sent by Amazon FBA - When sent to Amazon FBA
Order sent by Amazon MCF - When sent to Amazon MCF
Order sent to Shipedge - When sent to ShipEdge warehouse

Inventory Events

Inventory corrections - When inventory is adjusted or corrected
Inventory mirror - Real-time inventory synchronization (special feature)

Replenishment Events

Replenishment initiated - When a replenishment request is created
Replenishment received - When replenishment inventory is received

Return Events

Simple return order initiated - When a return order is created
Simple return order received - When a return order is received
Exchange now order initiated - When an exchange order is created
Exchange now order received - When an exchange order is received
Exchange on received order initiated - When exchange is initiated after receiving return
Exchange on received order received - When exchange order is received
Unexpected Return Order Received - When an unexpected return arrives

Webhook Versions

Most webhook events support multiple versions (v1, v2, v3) with different data formats:

v1 - Original format (legacy)
v2 - Enhanced format with more data fields (recommended)
v3 - Latest format (available for some events like orders/shipped)

Configuring a Webhook

Go to Webhooks Configuration

Navigate to My Account > Preferences > Webhooks.
Click Add New Webhook

Or edit an existing webhook if updating.
Select Event

Choose the event you want to monitor from the dropdown (e.g., “Order shipped”).
Select Version

Choose the version format (v1, v2, or v3 if available). Use v2 or v3 for best results.
Enter Webhook URL

Provide the full URL where ShipEdge should send notifications (e.g., https://your-server.com/webhooks/order-shipped).
Configure Status

Set webhook status to Active to enable it, or Inactive to disable temporarily.
Add Custom Headers (Optional)

Add custom HTTP headers if your server requires authentication or special headers.
Configure Authentication (Optional)

Select an authentication method if your server requires authentication.
Configure Certificate (Optional)

Enable certificate identification if your server requires SSL client certificates.
Save Webhook

Click Save to create the webhook. It will start working immediately if status is Active.

Webhook Configuration Fields

Required Fields:

Event - The event to monitor
Version - Data format version (v1, v2, or v3)
Address - Webhook URL endpoint
Status - Active or Inactive

Optional Fields:

Custom Headers - Additional HTTP headers (e.g., Authorization: Bearer token)
Authentication - Pre-configured authentication method
Certificate Identification - SSL client certificate for secure connections
Format - Response format (JSON is standard)

Webhook Payload Format

Webhooks send data as JSON in the HTTP POST request body. The exact structure depends on the event type and version.

Example: Order Shipped (v2)

{
  "event": "orders/shipped_v2",
  "account_id": 100,
  "order_id": 12345,
  "order_number": "ORD-001",
  "order_reference": "REF-123",
  "status": "shipped",
  "shipped_date": "2024-01-15 10:30:00",
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "shipping_method": "Ground",
  "customer": {
    "email": "customer@example.com",
    "name": "John Doe",
    "address": {
      "address1": "123 Main St",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90001",
      "country": "USA"
    }
  },
  "items": [
    {
      "sku": "PROD-001",
      "quantity": 2,
      "description": "Product Description"
    }
  ],
  "total": 59.98,
  "shipping_cost": 5.99
}

Example: Inventory Correction (v2)

{
  "event": "inventory/corrections_v2",
  "account_id": 100,
  "correction_id": 789,
  "sku": "PROD-001",
  "location": "A-01",
  "bin": "BIN-001",
  "previous_quantity": 50,
  "new_quantity": 45,
  "adjustment": -5,
  "reason": "Cycle count adjustment",
  "user": "warehouse_user",
  "timestamp": "2024-01-15 14:20:00"
}

Receiving Webhooks

Your webhook endpoint should:

Accept POST Requests: Webhooks are sent via HTTP POST
Parse JSON: Extract data from the JSON request body
Validate Data: Verify the data is valid and from ShipEdge
Process Event: Handle the event appropriately (update database, send notifications, etc.)
Return 200 OK: Respond with HTTP 200 to confirm receipt

Example Webhook Handler (PHP)

<?php
// Get the raw POST data
$payload = file_get_contents('php://input');
$data = json_decode($payload, true);

// Validate the data
if (!$data || !isset($data['event'])) {
    http_response_code(400);
    exit('Invalid webhook data');
}

// Process based on event type
switch ($data['event']) {
    case 'orders/shipped_v2':
        // Handle order shipped
        $orderId = $data['order_id'];
        $orderNumber = $data['order_number'];
        $trackingNumber = $data['tracking_number'];

        // Update your system
        updateOrderStatus($orderId, 'shipped', $trackingNumber);
        sendCustomerNotification($orderNumber, $trackingNumber);
        break;

    case 'inventory/corrections_v2':
        // Handle inventory correction
        $sku = $data['sku'];
        $newQuantity = $data['new_quantity'];

        // Update inventory in your system
        updateInventory($sku, $newQuantity);
        break;

    default:
        // Unknown event type
        error_log("Unknown webhook event: " . $data['event']);
}

// Always return 200 OK
http_response_code(200);
echo 'OK';
?>

Example Webhook Handler (Node.js)

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

app.use(express.json());

app.post('/webhooks/order-shipped', (req, res) => {
  const data = req.body;

  // Validate the data
  if (!data.event || !data.order_id) {
    return res.status(400).send('Invalid webhook data');
  }

  // Process the event
  if (data.event === 'orders/shipped_v2') {
    const { order_id, order_number, tracking_number } = data;

    // Update your system
    updateOrderStatus(order_id, 'shipped', tracking_number);
    sendCustomerNotification(order_number, tracking_number);
  }

  // Always return 200 OK
  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

Webhook Security

HTTPS Required

Always use HTTPS URLs for webhooks to encrypt data in transit. ShipEdge will not send webhooks to HTTP endpoints in production.

Authentication

Use custom headers or authentication methods to verify requests are from ShipEdge:

Option 1: Custom Header

Authorization: Bearer your-secret-token

Option 2: Authentication Configuration Configure authentication in the webhook settings using pre-configured authentication methods.

Certificate Identification

For enhanced security, enable certificate identification to use SSL client certificates.

IP Whitelisting

If possible, whitelist ShipEdge server IPs on your firewall (contact support for IP ranges).

Webhook Logs

ShipEdge maintains logs of all webhook attempts. You can view logs to:

Monitor Success: See which webhooks were delivered successfully
Debug Failures: Identify why webhooks failed (timeout, invalid URL, etc.)
Resend Failed Webhooks: Retry webhooks that failed to deliver

Accessing Webhook Logs

Go to My Account > Preferences > Webhooks
Click on Webhook logs tab
View logs filtered by:
- Date range
- Event type
- Status (success/failure)
- Webhook URL

Resending Failed Webhooks

Go to My Account > Preferences > Webhooks
Click on Resend webhooks tab
Select failed webhooks to resend
Click Resend to retry delivery

💡 Best Practices

Use HTTPS

Always use HTTPS URLs for webhooks to ensure data is encrypted in transit.

Respond Quickly

Process webhooks quickly and return HTTP 200 immediately. ShipEdge times out after 10 seconds.

Handle Duplicates

Implement idempotency to handle duplicate webhook deliveries gracefully.

Validate Data

Always validate webhook data before processing to ensure it’s valid and from ShipEdge.

Use Latest Versions

Use v2 or v3 webhook versions when available for more complete data and better structure.

Monitor Logs

Regularly check webhook logs to ensure successful delivery and identify issues early.

Test Webhooks

Test your webhook endpoint thoroughly before going live to ensure it handles all event types correctly.

Implement Retry Logic

If your server is temporarily unavailable, ShipEdge will retry, but implement your own retry logic for critical events.

Troubleshooting

Webhooks Not Received

Common causes:

Webhook status is Inactive
Invalid or unreachable URL
Server timeout (webhook must respond within 10 seconds)
Firewall blocking requests
SSL certificate issues

Solution:

Verify webhook status is Active
Test the URL manually (should accept POST requests)
Check webhook logs for error messages
Verify firewall allows ShipEdge server IPs
Ensure SSL certificate is valid if using HTTPS

Webhooks Timing Out

Common causes:

Slow server response
Heavy processing in webhook handler
Database queries taking too long

Solution:

Return HTTP 200 immediately after receiving webhook
Process data asynchronously (queue for background processing)
Optimize database queries
Use a message queue for heavy processing

Duplicate Webhooks

Common causes:

ShipEdge retrying failed webhooks
Network issues causing retries
Multiple webhooks configured for same event

Solution:

Implement idempotency using order_id or event_id
Check for duplicate webhook configurations
Use database unique constraints to prevent duplicate processing

Invalid Data Format

Common causes:

Using wrong webhook version
Expecting different data structure
Missing required fields

Solution:

Verify webhook version matches your expectations
Review webhook payload examples for your event type
Handle missing fields gracefully in your code
Update to latest webhook version if available

API Overview - General API information
REST API v4 (OMS) - OMS endpoints documentation
REST API v4 (WMS) - WMS endpoints documentation
API Authentication - Authentication guide

Next Step: REST API v4 (OMS) - Learn to use OMS endpoints for order and inventory management

Webhooks

Why Use Webhooks?

Real-Time Updates

Automate Workflows

Reduce API Calls

Stay Synchronized

How Webhooks Work

Accessing Webhook Configuration

OMS (Order Management System)

WMS (Warehouse Management System)

Available Webhook Events

Order Events

Inventory Events

Replenishment Events

Return Events

Webhook Versions

Configuring a Webhook

Webhook Configuration Fields

Webhook Payload Format

Example: Order Shipped (v2)

Example: Inventory Correction (v2)

Receiving Webhooks

Example Webhook Handler (PHP)

Example Webhook Handler (Node.js)

Webhook Security

HTTPS Required

Authentication

Certificate Identification

IP Whitelisting

Webhook Logs

Accessing Webhook Logs

Resending Failed Webhooks

💡 Best Practices

Use HTTPS

Respond Quickly

Handle Duplicates

Validate Data

Use Latest Versions

Monitor Logs

Test Webhooks

Implement Retry Logic

Troubleshooting

Webhooks Not Received

Webhooks Timing Out

Duplicate Webhooks

Invalid Data Format

Related Links