Webhook Events

Learn about the webhook events available in the Curosa API and how to handle them

Overview

Webhooks allow you to receive real-time notifications when events occur in the Curosa platform. When an event occurs, we send an HTTP POST request to each active webhook URL that is subscribed to that event. This enables you to integrate your systems with Curosa and respond to events automatically.

Webhook Delivery

When an event occurs, we send a single HTTP POST request to each webhook URL that is active and subscribed to that event.

Request Format

Property	Value
Method	`POST`
URL	The webhook URL you configured
Headers	`Content-Type: application/json`
Body	JSON object (see below)

Request Body Structure

Every webhook request body follows this consistent structure:

Field	Type	Description
`event`	string	Event identifier (e.g., `NewOrderCreated`). Use this to route or handle the event.
`data`	object	Event-specific payload. Structure depends on the `event` type (see event details below).
`timestamp`	string	ISO 8601 datetime when the request was sent (e.g., `2026-02-05T14:30:00.000000Z`).

Available Events

NewOrderCreated

Sent when a new customer order is created that includes your products. One webhook call is sent per order (so one order group with multiple supplier orders will trigger one call per supplier order).

Event Identifier: "NewOrderCreated"

Data Structure:

Path	Type	Description
`data.order`	object	The order that was created
`data.order.id`	integer	Internal order ID
`data.order.order_number`	string \| null	Human-readable order number (if set)
`data.order.status`	string	Order status (e.g., `pending`)
`data.order.allocation_status`	string	Stock allocation status (e.g., `unallocated`, `allocated`)
`data.order.currency`	string	Currency code (e.g., `GBP`)
`data.order.items_cost_total`	number	Total cost of items on the order
`data.order.created_at`	string \| null	ISO 8601 datetime when the order was created
`data.customer`	object \| null	Customer linked to the order, or `null` if not set
`data.customer.id`	integer	Internal customer ID
`data.customer.name`	string	Customer display name

Example Request:

{
  "event": "NewOrderCreated",
  "data": {
    "order": {
      "id": 12345,
      "order_number": "ORD-2026-001234",
      "status": "pending",
      "allocation_status": "unallocated",
      "currency": "GBP",
      "items_cost_total": 150.00,
      "created_at": "2026-02-05T14:30:00.000000Z"
    },
    "customer": {
      "id": 678,
      "name": "Jane Smith"
    }
  },
  "timestamp": "2026-02-05T14:30:01.000000Z"
}

Webhook Delivery and Retries

Asynchronous Delivery: Webhooks are sent asynchronously (queued). A slight delay after the event occurs is normal.
Delivery Status: Delivery status (e.g., last success or failure) is not currently exposed in the UI.
Retry Behavior: If your endpoint returns a non-2xx status code or we cannot reach it (e.g., timeout), we log the failure and may retry according to our queue configuration.

Handling Unknown Events

More events may be added in the future. Your webhook endpoint should be designed to:

Ignore unknown event values gracefully, or
Log unknown events for support and debugging purposes

This ensures your integration remains stable as new event types are introduced to the API.