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.

Webhooks Overview

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

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 (versions v1, v2, v3, v4)
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 Dropshipper filtered by order type - When fulfilled by dropshipper, filtered by order type
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

Billing Events

Statement created - When a billing statement is created

Webhook Versions

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

v1 - Original format (legacy)
v2 - Enhanced format with more data fields
v3 - Extended format (available for some events like orders/shipped, adds store filter)
v4 - Latest format for orders/shipped (adds store filter and remove order number suffix option)

Configuring a Webhook

Go to Webhooks Configuration

Navigate to My Account > Preferences > Webhooks.
Click Add webhook

Or edit an existing webhook and click “Update webhook” to save changes.
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 Address

Provide the full URL where ShipEdge should send notifications (e.g., http://your.address.com). The field is labeled “Address”.
Configure Status

Set webhook status to Enable to activate it, or Disable to turn it off temporarily.
Add Custom Headers (Optional)

Add custom HTTP headers (key/value pairs) if your server requires authentication or special headers.
Configure Custom Authentication (Optional)

Select a pre-configured authentication from the “Custom authentication” dropdown, or add one at Authentications first.
Identify with a certificate (Optional)

Set to Yes if your server requires SSL client certificates. Use No for standard connections. A “Download certificate” button is available at the top of the page.
Character encoding (Optional)

Select encoding (none, ASCII, UTF-8, etc.) if needed for your endpoint.
Save Webhook

Click “Add webhook” to create, or “Update webhook” to save changes. Success messages: “New webhook added.” or “Webhook updated.” The webhook works immediately if status is Enable.

Webhook Configuration Fields

Required Fields:

Event - The event to monitor
Version - Data format version (v1, v2, v3, or v4 when available)
Address - Webhook URL endpoint (full URL where POST requests are sent)
Status - Enable or Disable
Format - Response format (JSON is standard)

Optional Fields:

Custom header - Additional HTTP headers (key/value pairs, up to 3)
Custom authentication - Pre-configured authentication from Authentications page
Identify with a certificate - Yes/No for SSL client certificate
Character encoding - none, ASCII, UTF-8, Windows-1252, ISO-8859-15, etc.

Event-Specific Filters (shown when applicable):

Order any status change - Statuses checkboxes (backorder, canceled, pending, processing, shipped, etc.)
Order shipped with shipping method - Filter (include/exclude) and shipping method codes
Order shipped by store - Store multi-select
Order shipped by order type - Include/exclude order types
Order shipped v3/v4 - Store filter; v4 adds “Remove order number suffix” option

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: Custom authentication Configure authentication in the webhook settings using pre-configured methods from the Authentications page.

Identify with a certificate

For enhanced security, set “Identify with a certificate” to Yes to use SSL client certificates. Download the certificate from the button at the top of the webhooks page.

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 the Webhook logs tab in the navigation
View logs filtered by:
- Date range
- Event type
- Status (success/failure)
- Webhook URL

Adjacent tabs: Schedule reports, Schedule reports logs, Resend schedule reports, Authentications.

Resending Failed Webhooks

Go to My Account > Preferences > Webhooks
Click the 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 Disable
Invalid or unreachable URL
Server timeout (webhook must respond within 10 seconds)
Firewall blocking requests
SSL certificate issues

Solution:

Verify webhook status is Enable
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
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)

Available Webhook Events

Order Events

Inventory Events

Replenishment Events

Return Events

Billing 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

Identify with a certificate

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