API Documentation & Guides

# Webhooks & Event Notifications

The API supports webhooks for order status and unsolicited cease events. Configure your endpoint to receive notifications and process them as described below.

# Quick Start Workflow

  1. Register Your Endpoint:
    • Register your webhook endpoint with your account manager or via the API portal (if available).
  2. Receive Events:
    • Your endpoint must accept POST requests with a JSON body.
  3. Validate and Process:
    • Validate the event (e.g., signature, secret) and process idempotently.
  4. Acknowledge Receipt:
    • Return a 2xx status to acknowledge successful processing.

# Field-Level Guidance & Enums

Field Type Required Description Example / Enum Values
eventType string Yes Type of event ORDER_STATUS_UPDATE, UNSOLICITED_CEASE
orderId integer No Order identifier (for order status events) 127
serviceId string No Service identifier (for cease events) f41b356c-...
status string No Order status (see Order Management) COMPLETED, IN_PROGRESS, FAILED
reasonCode string No Reason for cease (see enums in Order Mgmt) NO_AUTHORISATION, ...
timestamp string Yes Event timestamp (ISO 8601) 2025-07-14T10:00:00.000Z
details object No Additional event details { previousStatus, notes }
notes string No Additional notes "Cease initiated by supplier."

# Event Types

  • ORDER_STATUS_UPDATE: Order status changed (see Order Management for possible statuses)
  • UNSOLICITED_CEASE: Service ceased without direct order

# Supported Webhooks

  • Order Status Webhook: Notifies you of changes to order status (e.g., in progress, completed, failed, cancelled).
  • Unsolicited Cease Webhook: Notifies you when a service is ceased without a direct order (e.g., due to external action).

# Example: Order Status Webhook Payload

{
  "eventType": "ORDER_STATUS_UPDATE",
  "orderId": 127,
  "status": "COMPLETED",
  "timestamp": "2025-07-14T10:00:00.000Z",
  "details": {
    "previousStatus": "IN_PROGRESS",
    "notes": "Order completed successfully."
  }
}

# Example: Unsolicited Cease Webhook Payload

{
  "eventType": "UNSOLICITED_CEASE",
  "serviceId": "f41b356c-11d2-4d65-b8b3-258461af9c2c",
  "reasonCode": "NO_AUTHORISATION",
  "timestamp": "2025-07-14T11:00:00.000Z",
  "notes": "Cease initiated by supplier."
}

# Event Types

  • ORDER_STATUS_UPDATE: Order status changed (see Order Management for possible statuses)
  • UNSOLICITED_CEASE: Service ceased without direct order

# Webhook Configuration

  • Register your webhook endpoint with your account manager or via the API portal (if available).
  • Your endpoint must accept POST requests with a JSON body.
  • Secure your endpoint (e.g., with a secret, IP allowlist, or signature verification).

← FAQ →