Webhooks

Webhooks allow your external systems to receive real-time notifications when events occur in your OpenBoxes instance. Instead of polling the API for changes, configure a webhook URL and OpenBoxes Lift will push event data to your endpoint as events happen.

Roadmap Feature: Webhooks are currently on the OpenBoxes Lift roadmap. This page describes the planned functionality and API design. Subscribe to the Lift changelog for updates on availability.

How Webhooks Work

1. You register a webhook URL in the Lift portal for your tenant
2. When a subscribed event occurs, Lift sends an HTTP POST to your URL
3. Your endpoint processes the payload and returns a 200 response
4. If delivery fails, Lift retries with exponential backoff

OpenBoxes Lift                     Your Server
      │                                │
      │  Event occurs (e.g., shipment  │
      │  status changes to SHIPPED)    │
      │                                │
      ├──── POST /your/webhook/url ───>│
      │     { event payload }          │
      │                                │
      │<──── 200 OK ──────────────────│
      │                                │

Planned Event Types

The following events are planned for webhook support:

Inventory Events

Event	Description
inventory.adjusted	Inventory adjustment recorded
inventory.received	Stock received at a location
inventory.transferred	Stock transferred between locations

Stock Movement Events

Event	Description
stockMovement.created	New stock movement created
stockMovement.shipped	Stock movement marked as shipped
stockMovement.received	Stock movement received at destination
stockMovement.canceled	Stock movement canceled

Purchase Order Events

Event	Description
purchaseOrder.created	New purchase order created
purchaseOrder.placed	Purchase order submitted to supplier
purchaseOrder.received	Purchase order fully received

Product Events

Event	Description
product.created	New product added to catalog
product.updated	Product details modified

Payload Format

Webhook payloads follow a consistent JSON structure:

{
  "id": "evt-abc123def456",
  "type": "stockMovement.shipped",
  "timestamp": "2025-04-01T14:30:00Z",
  "tenantId": "acme",
  "data": {
    "id": "sm-001",
    "identifier": "SM-00142",
    "name": "Transfer to Regional Depot",
    "status": "SHIPPED",
    "origin": {
      "id": "loc-001",
      "name": "Central Warehouse"
    },
    "destination": {
      "id": "loc-002",
      "name": "Regional Depot"
    },
    "dateShipped": "2025-04-01T14:30:00Z",
    "lineItems": [
      {
        "product": { "id": "prod-001", "name": "Ibuprofen 200mg" },
        "quantityShipped": 1000
      }
    ]
  }
}

Payload Fields

Field	Type	Description
id	string	Unique event ID (for deduplication)
type	string	Event type identifier
timestamp	string	ISO 8601 timestamp of when the event occurred
tenantId	string	Your tenant identifier
data	object	Event-specific data (the affected resource)

Configuring Webhooks

Webhook configuration will be available in the Lift portal under Settings > Integrations > Webhooks.

Configuration Options

Setting	Description
URL	HTTPS endpoint to receive webhook POST requests
Events	Which event types to subscribe to
Secret	Shared secret for request signature verification
Active	Enable or disable the webhook

Signature Verification

Each webhook request includes a signature header for verifying authenticity:

X-Webhook-Signature: sha256=a1b2c3d4e5f6...

Verify the signature by computing HMAC-SHA256 of the request body using your webhook secret:

# Example: verify webhook signature
expected=$(echo -n "$REQUEST_BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | cut -d' ' -f2)
if [ "$expected" = "$RECEIVED_SIGNATURE" ]; then
  echo "Signature valid"
fi

Retry Policy

If your endpoint does not return a 2xx response, Lift retries delivery with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	12 hours

After 5 failed attempts, the event is marked as failed. Failed events can be viewed and manually retried from the Lift portal.

Best Practices

• Return 200 quickly: Process webhook payloads asynchronously. Return 200 OK immediately and handle the event in a background job.
• Handle duplicates: Use the id field to deduplicate events. Network retries may deliver the same event more than once.
• Verify signatures: Always validate the X-Webhook-Signature header to ensure requests originate from Lift.
• Use HTTPS: Webhook URLs must use HTTPS. Plain HTTP endpoints are rejected.
• Monitor failures: Check the Lift portal for failed deliveries and investigate endpoint availability issues promptly.

Use Cases

Scenario	Events to Subscribe
ERP sync	purchaseOrder.*, inventory.*
Shipment tracking dashboard	stockMovement.shipped, stockMovement.received
Low stock alerts	inventory.adjusted, inventory.transferred
Product catalog sync	product.created, product.updated
Audit logging	All events

Coming Soon

Webhook support is actively being developed. Planned enhancements beyond the initial release include:

• Event filtering: Subscribe to events for specific locations or products
• Batch delivery: Receive multiple events in a single POST for high-volume tenants
• Event replay: Re-deliver events from a specific point in time
• Webhook logs: Full request/response logs for debugging in the Lift portal