POST

/v1/webhooks

Creates a new webhook subscription for the specified event. Webhooks allow your application to receive real-time notifications when specific events occur in the system. This endpoint enables you to configure automated HTTP POST requests that will be sent to your specified URL whenever the subscribed event is triggered. You can customize which clients trigger the webhook and control the active state of the subscription.

Welcome to Logiwa IO Webhook Platform

Receive real-time event notifications from your Logiwa IO warehouse via webhooks.

Get Started in Minutes

Authenticate

Obtain your JWT authentication token from your dashboard

Choose Events

Select which events you want to monitor and receive notifications for

Create Webhook

Configure your webhook endpoint URL and event subscriptions

Receive Events

Start receiving real-time notifications at your endpoint

Ready to get started?

Follow our step-by-step guide to begin receiving webhooks

Frequently Asked Questions

Get answers to common questions about webhooks and the Logiwa system

The Logiwa system uses a distributed cache to optimize performance. When you create or update a webhook, the change is immediately persisted to the database, but the cache layer needs time to synchronize. This means it may take up to 5 minutes for your webhook to become fully active.

Timeline:

Immediate (0-1 min): Webhook created/updated and stored in database
1-5 min: Configuration propagated through cache layer to all processing nodes
After 5 min: Webhook fully active and receiving all events

ℹ️ Note: This applies to all webhook changes including creation, URL changes, client filtering modifications, and status toggles.

💡 Tip: While waiting for the cache to propagate, you can verify your webhook by:

Calling GET /v1/webhooks/{id} to check if the webhook exists
Listing all webhooks with GET /v1/webhooks
Checking the webhook's active status in the response

Yes! You can create multiple webhooks for the same event, but they must have different base URLs.

Valid Scenario:

// Webhook 1 - Send to CRM
POST /v1/webhooks
{
  "event": "ShipmentOrderCreated",
  "url": "https://crm.example.com/webhooks/shipments",
  "allowedClientIdentifiers": []
}

// Webhook 2 - Send to Analytics (different base URL)
POST /v1/webhooks
{
  "event": "ShipmentOrderCreated",
  "url": "https://analytics.example.com/webhooks/shipments",
  "allowedClientIdentifiers": []
}

// Result: ✅ Both webhooks are created successfully
// Event: ShipmentOrderCreated will be sent to both URLs

Invalid Scenario:

// Webhook 1 - Created first
POST /v1/webhooks
{
  "event": "ShipmentOrderCreated",
  "url": "https://api.example.com/webhooks/shipments",
  "allowedClientIdentifiers": []
}

// Webhook 2 - Attempt with same base URL (different path)
POST /v1/webhooks
{
  "event": "ShipmentOrderCreated",
  "url": "https://api.example.com/webhooks/shipments-v2",  // Same base URL!
  "allowedClientIdentifiers": []
}

// Result: ❌ HTTP 400 Bad Request
// Error: "A webhook for this event and base URL already exists"

Client identifiers allow you to control which clients' events trigger your webhook. This is useful in multi-tenant scenarios where you want to receive events only for specific clients.

Client Identifier Scenarios:

Scenario 1: Receive events from specific clients

{
  "event": "ProductInformationUpdated",
  "url": "https://api.example.com/webhook",
  "allowedClientIdentifiers": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  ]
}

// Result: Webhook receives events only from those 2 clients

Scenario 2: Receive events from all clients

{
  "event": "ProductInformationUpdated",
  "url": "https://api.example.com/webhook",
  "allowedClientIdentifiers": []
}

// Result: Webhook receives events from ALL clients (broadcast mode)

ℹ️ How Client IDs Work: The client identifiers (GUIDs) you provide are validated and converted to internal client IDs by the Logiwa system. Only the internal IDs are stored in the database for performance optimization.

📋 Need to find your client identifiers? Use the List Clients endpoint from the Logiwa OpenAPI to retrieve your available client identifiers.

Webhooks are delivered via HTTP POST requests to your specified URL. Each webhook request includes important security and context information in the headers and body.

Webhook Delivery Details:

// Your endpoint receives:
  POST 
  -H 'accept-encoding: gzip' 
  -H 'x-mylogiwa-topic: {{TOPIC_NAME}}' 
  -H 'x-mylogiwa-client-id: {{CLIENT_ID}}' 
  -H 'x-mylogiwa-subscription-id: {{SUBSCRIPTION_ID}}'
  -H 'x-mylogiwa-processing-duration: {{PROCESSING_DURATION_MS}}' 
  -H 'x-mylogiwa-hmac-sha256: {{HMAC_SIGNATURE}}' 
  -H 'x-mylogiwa-event-id: {{EVENT_ID}}' 
  -H 'content-type: application/json' 
  -H 'user-agent: EventSender/1.0' 
  -d '[
    {
      "Identifier": "{{PRODUCT_IDENTIFIER}}",
      "SKU": "{{PRODUCT_SKU}}",
      "ClientId": {{CLIENT_ID}}
    }
  ]'

ℹ️ Security Headers:

X-HMAC-Signature: HMAC-SHA256 signature for verifying authenticity
X-Timestamp: Request timestamp in Unix format
Authorization: Custom token you configured (if provided)

The webhook system implements intelligent retry logic to handle temporary failures. Requests are classified based on HTTP response codes to determine the appropriate action.

Failure Handling Logic:

2xx Success (200-299): Delivery successful, no retries needed
4xx Client Errors (400-499): Permanent failure (bad request, unauthorized, not found)
- No automatic retries
- Event marked as failed
- Check your endpoint configuration
5xx Server Errors (500-599): Temporary failure
- Automatic retry with exponential backoff
- Multiple retry attempts over time
- Event eventually marked as failed if retries exhausted
429 Too Many Requests: Rate limit hit
- Automatic retry after respecting Retry-After header
- Exponential backoff applied

💡 Best Practices:

Ensure your endpoint returns 2xx status for successful processing
Return 4xx errors only for genuinely invalid requests
Return 5xx errors for temporary failures (retryable conditions)
Monitor your endpoint health regularly

The Logiwa Webhook API uses JWT (JSON Web Tokens) for authentication. You need to obtain a valid token before making API requests.

Authentication Flow:

// Step 1: Get JWT token
POST /v1/auth/login
{
  "username": "your-username",
  "password": "your-password"
}

Response:
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2024-01-10T11:30:00Z"
}

// Step 2: Use token in webhook requests
POST /v1/webhooks
Headers:
{
  "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs...",
  "Content-Type": "application/json"
}
Body:
{
  "event": "ShipmentOrderCreated",
  "url": "https://api.example.com/webhook",
  "allowedClientIdentifiers": []
}

ℹ️ Token Management:

Tokens expire after a set period (check expires_at)
Use the refresh endpoint to get a new token
Always include "Bearer " prefix in Authorization header
Store tokens securely in your application

System blocks webhook URLs that match known webhook testing services. This protection prevents accidental misconfiguration and maintains production data integrity.

Blocked Domains:

webhook.site
www.catchhooks.com
webhooktrack.com
www.hooklistener.com
echopoint.dev
play.svix.com
webhookbox.io
hookable.sh
webhookapp.dev
webhook-box.com

Your webhook endpoint must respond within 10 seconds. If your endpoint takes longer than 10 seconds to respond, the request will be considered failed and will be retried according to the retry policy.

Timeout Behavior:

Response within 10 seconds: Delivery marked as successful
Response after 10 seconds: Request times out and is retried
No response: Connection timeout triggers retry logic

💡 Best Practice:

Respond immediately with HTTP 200 upon receiving the webhook
Process webhook data asynchronously in a background job
Don't perform long-running operations in the webhook handler
Use queues or message brokers for heavy processing
Monitor your endpoint response times regularly

⚠️ Important: Slow endpoints that consistently exceed the 10-second timeout will trigger excessive retries, potentially causing duplicate processing. Always optimize your webhook handlers for fast response times.

If your webhook endpoint is behind a firewall, you need to whitelist the following IP addresses to ensure webhook events can be delivered successfully:

IP Addresses to Whitelist:

18.116.226.248
3.151.75.183

⚠️ Important: If these IP addresses are not whitelisted, webhook delivery requests will be blocked by your firewall and events will fail. Make sure both IPs are added to your allowlist.

💡 Tip: After whitelisting, you can verify connectivity by creating a test webhook and checking if events are delivered to your endpoint.

Every webhook request includes the X-Mylogiwa-Processing-Duration header, which provides the total duration (in milliseconds) from when the event was created to when it was delivered to your endpoint.

Get Started with Webhooks

Start receiving real-time event notifications in minutes

🚀

Quick Start Guide

Quick Start

Welcome! You can start receiving webhooks immediately. The webhook system is ready to use right out of the box.

Getting Started in 4 Steps:

Get Available Events

Choose from the supported events below to subscribe your webhook. You can also call GET /v1/events to retrieve this list programmatically.

Supported Events:

Event Name	Description	V1 Event Name
`ShipmentStatusChanged`	Triggered when shipment order status changes in WMS	`wms/shipmentorder/statuschange`
`ShipmentOrderCreated`	Triggered when a new shipment order is created in WMS	`wms/shipmentorder/create`
`ShipmentDetailsUpdated`	Triggered when shipment details are updated in WMS	`wms/shipmentorder/update`
`ShipmentDispatched`	Triggered when a shipment is dispatched in WMS	`wms/shipmentorder/shipment`
`ProductCreated`	Triggered when a new product is created in WMS	`wms/product/create`
`ProductInformationUpdated`	Triggered when product information is updated in WMS	`wms/product/update`
`PurchaseOrderStatusChanged`	Triggered when purchase order status changes in WMS	`wms/purchaseorder/statuschange`
`InventoryMovementRecorded`	Triggered when inventory movement is recorded in WMS	`wms/inventory/transaction`

Prepare Your Endpoint

Set up an HTTPS endpoint that can receive POST requests. Your endpoint should respond within 10 seconds and be ready to handle webhook payloads with HMAC signature verification.

Subscribe to Events

Use the Webhooks API to create subscriptions for the events you want to receive. Specify your endpoint URL, the event type, and optionally filter by specific client identifiers.

Start Receiving Events

That's it! Your endpoint will start receiving webhook events immediately. Monitor your logs, verify HMAC signatures, and track delivery performance using the provided headers.

💡 Quick Tips:

Use the Events API to discover all available event types before subscribing
Start with a single event type to test your integration
Implement HMAC signature verification for security
Use the X-Mylogiwa-Processing-Duration header to monitor latency
Set up logging to track webhook deliveries
Test with development environment first
🔒 Firewall Notice: If you have a firewall, don't forget to add our IP addresses to your whitelist. See the Q&A section for the full list of IPs.

Start With Authentication

📚 Helpful Resources

📖

API Documentation

Complete API reference with examples and code samples

View Docs →

❓

Q&A Section

Answers to common questions about webhooks

View Q&A →

Parameters

url string required

The destination URL where webhook events will be sent via HTTP POST. Must be a valid HTTPS URL.

Example: "https://api.example.com/webhooks/orders"

Validation: Must be a valid HTTPS URL, maximum length 2048 characters

event string required

The event ID that triggers this webhook. This must be a valid event ID obtained from the /v1/events endpoint. The system validates that the event exists and is active before creating the webhook.

Example: "ShipmentOrderCreated"

Validation: Must be a valid, active event ID from the events list. Call GET /v1/events to retrieve available events.

allowedClientIdentifiers array required

Array of client GUIDs that this webhook should trigger for. Use an empty array to trigger for all clients.

Example: ["a1b2c3d4-e5f6-7890-abcd-ef1234567890", "b2c3d4e5-f6a7-8901-bcde-f12345678901"] or [] for all clients

name string optional

User-friendly name for the webhook. If not provided, a name will be auto-generated based on the event type.

Example: "Order Processing Webhook"

active boolean optional

Whether the webhook is active and should receive events. Defaults to true if not specified.

Example: true

Response Schema

Returns a webhook object if successful. The response includes the generated webhook ID and complete webhook configuration.

id string Unique identifier for the webhook

name string User-friendly name for the webhook

url string Destination URL where webhook events will be sent

event string Event ID that triggers this webhook

description string Optional description of the webhook

headers object Custom headers to include with webhook requests

active boolean Whether the webhook is active and should receive events

created_at timestamp ISO 8601 timestamp of creation

updated_at timestamp ISO 8601 timestamp of last update

Status Codes

201 Created Webhook created successfully

400 Bad Request Invalid parameters or malformed request

401 Unauthorized Invalid or missing authentication token

422 Unprocessable Entity URL validation failed or event type not supported

Example code

curl -X POST https://webhook.logiwa.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/shipments",
    "event": "ShipmentOrderCreated",
    "allowedClientIdentifiers": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890", "b2c3d4e5-f6a7-8901-bcde-f12345678901"],
    "active": true,
    "name": "Shipment Order Webhook",
    "description": "Webhook for processing new shipment order notifications",
    "headers": {
      "Authorization": "Bearer webhook-token",
      "X-Custom-Header": "logiwa-webhook"
    }
  }'

const response = await fetch('https://webhook.logiwa.com/v1/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://api.example.com/webhooks/shipments',
    event: 'ShipmentOrderCreated',
    allowedClientIdentifiers: ['a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'b2c3d4e5-f6a7-8901-bcde-f12345678901'],
    active: true,
    name: 'Shipment Order Webhook',
    description: 'Webhook for processing new shipment order notifications',
    headers: {
      'Authorization': 'Bearer webhook-token',
      'X-Custom-Header': 'logiwa-webhook'
    }
  })
});

const data = await response.json();
console.log(data);

import requests

url = "https://webhook.logiwa.com/v1/webhooks"
headers = {
    "Authorization": "Bearer YOUR_JWT_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "url": "https://api.example.com/webhooks/shipments",
    "event": "ShipmentOrderCreated",
    "allowedClientIdentifiers": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890", "b2c3d4e5-f6a7-8901-bcde-f12345678901"],
    "active": True,
    "name": "Shipment Order Webhook",
    "description": "Webhook for processing new shipment order notifications",
    "headers": {
        "Authorization": "Bearer webhook-token",
        "X-Custom-Header": "logiwa-webhook"
    }
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
print(data)

Sample Response

Response 201 Created

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Shipment Order Webhook",
  "url": "https://api.example.com/webhooks/shipments",
  "event": "ShipmentOrderCreated",
  "description": "",
  "headers": {},
  "active": true,
  "created_at": "2024-01-10T10:30:00Z",
  "updated_at": "2024-01-10T10:30:00Z"
}