Notification

Notifications enable external systems to receive updates when specific events occur on a Norce Checkout order. When an order changes in a way that matches a notification's scope, Norce Checkout sends an HTTP POST request to the configured URL with details about the event.

How Notifications Work

Notifications are registered on an order and define what changes should trigger an outbound call. When a change occurs that matches the notification scope, the Order Service publishes an event to an internal message bus. The Notification Service picks up the event, creates an Event record, and attempts to invoke the notification URL. Each delivery attempt is logged with the HTTP status code and response details.

There are two ways to add notifications to an order:

1. Programmatically: An adapter can register notifications when performing other operations on the order. For example, a payment adapter creating a payment can simultaneously register a notification to be informed when the order completes.

2. Via Configuration: Define notifications in your adapter configuration so they are automatically added to every order created in that channel.

Notification Structure

A notification consists of a URL to call, the HTTP method, optional headers, and a scope that defines which order changes should trigger the notification:

{
  "url": "https://your-system.example.com/webhooks/order-completed",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer your-webhook-secret",
    "Content-Type": "application/json"
  },
  "scope": {
    "state": ["completed"]
  }
}

Notification Scopes

The scope determines when a notification fires. Common scope configurations include:

Order State Changes: Trigger when the order reaches specific states.

{
  "scope": {
    "state": ["completed", "declined"]
  }
}

Payment Updates: Trigger when payment information changes.

{
  "scope": {
    "payment": true
  }
}

Shipping Updates: Trigger when shipping details are modified.

{
  "scope": {
    "shipping": true
  }
}

Example: ERP Integration Notification

A common use case is notifying an ERP system when an order completes. Register this notification via the Norce Adapter configuration or programmatically when the order is created:

{
  "url": "https://erp.example.com/api/orders/import",
  "method": "POST",
  "headers": {
    "X-API-Key": "erp-integration-key-12345",
    "Content-Type": "application/json"
  },
  "scope": {
    "state": ["completed"]
  }
}

When the order transitions to completed, Norce Checkout sends a POST request to the ERP endpoint with the order data in the request body.

Example: Order Confirmation Email Trigger

Trigger an email service when an order is accepted:

{
  "url": "https://email-service.example.com/send-confirmation",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer email-service-token"
  },
  "scope": {
    "state": ["accepted"]
  }
}

Notification Events and Retries

Each notification delivery attempt creates an Event record. The Event contains:

• Event ID: Unique identifier for the delivery attempt
• Order ID: The order that triggered the notification
• Timestamp: When the attempt was made
• Status Code: HTTP response code from the target URL
• Response Body: Response content (useful for debugging failures)

If a notification delivery fails (non-2xx response), you can retry it using the Notification API:

POST /api/v0/checkout/notifications/events/{eventId}/retry
X-Merchant: your-merchant
Authorization: Bearer your-token

Querying Notification Events

Use the Notification API to monitor delivery status and troubleshoot issues:

Get all events for an order:

GET /api/v0/checkout/notifications/events?orderId={orderId}
X-Merchant: your-merchant
Authorization: Bearer your-token

Get events by notification scope:

GET /api/v0/checkout/notifications/events?scope=state.completed
X-Merchant: your-merchant
Authorization: Bearer your-token

See the Notification API reference for complete endpoint documentation.