Webhooks API

Event notifications and webhook configuration endpoints.

Webhooks API

The Webhooks API allows you to configure and manage webhook endpoints that receive real-time notifications when specific events occur in the system.

Webhook Events

Smart Shelf can send webhook notifications for various events:

Product Events

product.created - New product added
product.updated - Product information changed
product.deleted - Product deactivated

Inventory Events

inventory.low_stock - Product stock below reorder point
inventory.out_of_stock - Product stock reached zero
inventory.movement - Stock movement recorded
inventory.adjustment - Inventory adjustment made

Order Events

order.created - New order placed
order.updated - Order status changed
order.shipped - Order shipped to customer
order.delivered - Order delivered
order.cancelled - Order cancelled

User Events

user.created - New user account created
user.updated - User information changed
user.login - User logged in

Webhook Payload Format

All webhooks include a standard payload structure:

{
  "id": "wh_123456",
  "event": "product.created",
  "created": 1640995200,
  "data": {
    "object": {
      "id": "prod_123",
      "name": "Smart Widget",
      // ... full object data
    },
    "previous_attributes": {
      // ... previous values for update events
    }
  },
  "api_version": "2024-01-15"
}

Webhook Security

Webhooks include a signature header for verification:

X-Signature: sha256=calculated_signature

To verify the signature:

const crypto = require('crypto')

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
  
  return `sha256=${expectedSignature}` === signature
}

Endpoints

GET /api/webhooks

Retrieve configured webhooks.

Response:

{
  "data": [
    {
      "id": "webhook_001",
      "url": "https://your-app.com/webhooks/inventory",
      "events": [
        "inventory.low_stock",
        "inventory.out_of_stock"
      ],
      "is_active": true,
      "secret": "whsec_...",
      "description": "Inventory alerts webhook",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}

POST /api/webhooks

Create a new webhook.

Request Body:

{
  "url": "https://your-app.com/webhooks/orders",
  "events": [
    "order.created",
    "order.updated",
    "order.shipped"
  ],
  "description": "Order management webhook",
  "is_active": true
}

Response:

{
  "data": {
    "id": "webhook_002",
    "url": "https://your-app.com/webhooks/orders",
    "events": [
      "order.created",
      "order.updated",
      "order.shipped"
    ],
    "is_active": true,
    "secret": "whsec_1a2b3c4d5e6f7g8h9i0j",
    "description": "Order management webhook",
    "created_at": "2024-01-16T00:00:00Z",
    "updated_at": "2024-01-16T00:00:00Z"
  }
}

PUT /api/webhooks/:id

Update an existing webhook.

Request Body:

{
  "url": "https://your-app.com/webhooks/orders-v2",
  "events": [
    "order.created",
    "order.updated",
    "order.shipped",
    "order.delivered"
  ],
  "is_active": true
}

Response:

{
  "data": {
    "id": "webhook_002",
    "url": "https://your-app.com/webhooks/orders-v2",
    "events": [
      "order.created",
      "order.updated",
      "order.shipped",
      "order.delivered"
    ],
    "updated_at": "2024-01-16T01:00:00Z"
  }
}

DELETE /api/webhooks/:id

Delete a webhook.

Response:

{
  "data": {
    "message": "Webhook successfully deleted"
  }
}

POST /api/webhooks/:id/test

Test a webhook by sending a test event.

Request Body:

{
  "event_type": "product.created"
}

Response:

{
  "data": {
    "webhook_id": "webhook_001",
    "test_event_id": "test_123",
    "status": "sent",
    "response_code": 200,
    "response_time": 250,
    "sent_at": "2024-01-16T01:30:00Z"
  }
}

GET /api/webhooks/:id/deliveries

Get webhook delivery history and status.

Query Parameters:

status (string): Filter by delivery status (success, failed, pending)
start_date (string): Start date for delivery log
end_date (string): End date for delivery log
page (number): Page number
limit (number): Items per page

Response:

{
  "data": [
    {
      "id": "delivery_001",
      "webhook_id": "webhook_001",
      "event_type": "inventory.low_stock",
      "event_id": "event_123",
      "status": "success",
      "response_code": 200,
      "response_time": 180,
      "response_body": "OK",
      "attempts": 1,
      "sent_at": "2024-01-15T16:00:00Z",
      "next_retry": null
    },
    {
      "id": "delivery_002",
      "webhook_id": "webhook_001",
      "event_type": "inventory.out_of_stock",
      "event_id": "event_124",
      "status": "failed",
      "response_code": 500,
      "response_time": 5000,
      "response_body": "Internal Server Error",
      "attempts": 3,
      "sent_at": "2024-01-15T15:30:00Z",
      "next_retry": "2024-01-15T16:30:00Z"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "hasMore": true
  }
}

POST /api/webhooks/:id/deliveries/:delivery_id/retry

Manually retry a failed webhook delivery.

Response:

{
  "data": {
    "delivery_id": "delivery_002",
    "status": "retrying",
    "attempts": 4,
    "retry_at": "2024-01-16T02:00:00Z"
  }
}

GET /api/webhooks/events

Get list of available webhook events.

Response:

{
  "data": {
    "events": [
      {
        "name": "product.created",
        "description": "Triggered when a new product is created",
        "category": "product"
      },
      {
        "name": "product.updated",
        "description": "Triggered when a product is modified",
        "category": "product"
      },
      {
        "name": "inventory.low_stock",
        "description": "Triggered when product stock falls below reorder point",
        "category": "inventory"
      },
      {
        "name": "order.created",
        "description": "Triggered when a new order is placed",
        "category": "order"
      }
    ],
    "categories": [
      {
        "name": "product",
        "description": "Product-related events"
      },
      {
        "name": "inventory",
        "description": "Inventory and stock events"
      },
      {
        "name": "order",
        "description": "Order lifecycle events"
      },
      {
        "name": "user",
        "description": "User account events"
      }
    ]
  }
}

Example Webhook Payloads

Product Created

{
  "id": "wh_123456",
  "event": "product.created",
  "created": 1640995200,
  "data": {
    "object": {
      "id": "prod_123",
      "name": "Smart Widget",
      "sku": "SW-001",
      "price": 49.99,
      "created_at": "2024-01-15T15:30:00Z"
    }
  },
  "api_version": "2024-01-15"
}

Inventory Low Stock

{
  "id": "wh_123457",
  "event": "inventory.low_stock",
  "created": 1640995800,
  "data": {
    "object": {
      "product_id": "prod_456",
      "product_name": "Basic Widget",
      "warehouse_id": "wh_789",
      "warehouse_name": "Main Warehouse",
      "current_stock": 15,
      "reorder_point": 20,
      "max_stock_level": 200
    }
  },
  "api_version": "2024-01-15"
}

Order Shipped

{
  "id": "wh_123458",
  "event": "order.shipped",
  "created": 1640996400,
  "data": {
    "object": {
      "id": "so_123",
      "order_number": "SO-2024-001",
      "customer_id": "cust_456",
      "status": "shipped",
      "tracking_number": "1Z999AA1234567890",
      "carrier": "UPS",
      "ship_date": "2024-01-16T14:30:00Z"
    }
  },
  "api_version": "2024-01-15"
}

Users

SDKs & Libraries