# Using Norce Commerce Event

Norce Commerce Event is a webhook solution and enables client solution's to listen for specific things that happens within the Norce Commerce platform.

The events are of two types:

- **Notifications**: This is events that requires rules and settings (maintained in the Admin UI) in Norce. This could be a change of a product status or when
an item has come into stock in the warehouse.
- **Events**: This is events that happens by themselves in the platform. This could be when a customer has been registered, or when a payment is reserved.


## Requirements

Norce Commerce Event uses HTTP webhooks as transport for events.

## Event types

In the [Admin UI]  you can se the list of built-in event types that can be listened to. They are grouped into:

| Category | Description | Resources (admin, docs, refs) |
|  --- | --- | --- |
| Customer | Changes to customer or company entities and their related entities, like account. | [CustomerChangedNotification](/api-reference/event/webhooks/openapi/customer/paths/customerchangednotification/post) ([admin](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/customerchangednotification/detail)), [CompanyChangedNotification](/api-reference/event/webhooks/openapi/customer/paths/companychangednotification/post) ([admin](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/companychangednotification/detail)) |
| Order | Order and other transactional events, like Order cancelled or confirmed. | [InvoiceCaptureCompletedEvent](/api-reference/event/webhooks/openapi/order/paths/invoicecapturecompletedevent/post) ([admin](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/invoicecapturecompletedevent/detail)),[OrderCancelledEvent](/api-reference/event/webhooks/openapi/order/paths/ordercancelledevent/post) ([admin](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/ordercancelledevent/detail)),[OrderConfirmedEvent](/api-reference/event/webhooks/openapi/order/paths/orderconfirmedevent/post) ([admin](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/orderconfirmedevent/detail)),[OrderDeliveredEvent](/api-reference/event/webhooks/openapi/order/paths/orderdeliveredevent/post) ([admin](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/orderdeliveredevent/detail)),[OrderPartlyDeliveredEvent](/api-reference/event/webhooks/openapi/order/paths/orderpartlydeliveredevent/post) ([admin](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/orderpartlydeliveredevent/detail)),[OrderReadyForPickupEvent](/api-reference/event/webhooks/openapi/order/paths/orderreadyforpickupevent/post) ([admin](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/orderreadyforpickupevent/detail)),[OrderPaymentReceivedEvent](/api-reference/event/webhooks/openapi/order/paths/orderpaymentreceivedevent/post) ([admin](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/orderpaymentreceivedevent/detail)),[OrderReceivedEvent](/api-reference/event/webhooks/openapi/order/paths/orderreceivedevent/post) ([admin](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/orderreceivedevent/detail)),[SubscriptionFailedEvent](/api-reference/event/webhooks/openapi/order/paths/subscriptionfailedevent/post) ([admin](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/subscriptionfailedevent/detail)) |
| Product | Product, Price or stock changes. | [SkuOnHandBreakPointNotification](/api-reference/event/webhooks/openapi/product/paths/skuonhandbreakpointnotification/post) ([admin](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/skuonhandbreakpointnotification/detail)),[SkuPriceChangedNotification](/api-reference/event/webhooks/openapi/product/paths/skupricechangednotification/post) ([admin](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/skupricechangednotification/detail)),[SkuChangedNotification](/api-reference/event/webhooks/openapi/product/paths/skuchangednotification/post) ([admin](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/skuchangednotification/detail)),[TranslationRequestedNotification](/api-reference/event/webhooks/openapi/product/paths/translationrequestednotification/post) ([admin](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/translationrequestednotification/detail)) |
| Supplier | Suppler products, prices or stock changes. | [SupplierSkuChangedNotification](/api-reference/event/webhooks/openapi/supplier/paths/supplierskuchangednotification/post) ([admin](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/supplierskuchangednotification/detail)),[SupplierSkuOnHandChangedNotification](/api-reference/event/webhooks/openapi/supplier/paths/supplierskuonhandchangednotification/post) ([admin](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/supplierskuonhandchangednotification/detail)),[SupplierSkuPriceChangedNotification](/api-reference/event/webhooks/openapi/supplier/paths/supplierskupricechangednotification/post) ([admin](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/supplierskupricechangednotification/detail)) |
| System | Notifications of system events, like Norce [Storm] Connect Jobs. | [JobCompletedEvent](/api-reference/event/webhooks/openapi/system/paths/jobcompletedevent/post) ([admin](https://norce-open-demo.admin-se.playground.norce.tech/integration/event/jobcompletedevent/detail)) |


## Event configurations

For every event type you want to listen for, you need to activate them in the Admin
UI [here](https://norce-open-demo.admin-se.playground.norce.tech/integration/event).

### Configurations in the Admin UI

![Event configurations](/assets/norce-event-configuration-1.d0fef84c5e74dc1a775afedd2be729b462e277a0a81aeaa578081ffefc7678e1.003e135d.png)

1. `ON/OFF`
Activate the webhook by switching to "on" after all required settings are added. Set to off to disable event tracking. Note that Norce will not track events
during the time an event is "off".
2. `Url`
This is your external endpoint that the webhook should post to.
3. `Headers`
Add your own headers, for example an authorization token. Only static values are allowed.
4. `Event metadata`
Describes the properties that is posted as json to the endpoint url. These are different for each event type.
5. `Event Settings`
Some event types have Event Settings in a separate Tab, that can be configured, see more [here](/developer-portal/system-integration/norce-event-settings).


## Technical information

### Retries and TTL

Norce will retry the http POST if we get any non-20X HTTP response code. The webhook will follow redirects. If the post is unsuccessful, a backoff retry
policy is used which will increase the interval between each retry. The backoff policy delays are:

- 5 seconds (between initial attempt and first retry)
- 10 seconds (between first and second retry)
- 15 seconds (between second and third retry)
- 30 seconds (etc...)
- 1 minute
- 2 minutes
- 5 minutes
- 10 minutes
- 15 minutes
- 30 minutes
- 1 hour
- 2 hours
- 3 hours
- 4 hours
- 5 hours
- 6 hours


The delay between each retry as stated above is the minimum delay, the delay can be longer. In total the above intervals
adds up to a minimum of 16 retries during ca 22 hrs.

### Timeout

The timeout for the http POST request is 5 seconds. If failed, a retry will be made according to the backoff policy.
After the retries are exhausted, the event will be marked as dead and will not be retried again.

See [monitor events](#monitoring-events) below for more information about event delivery logging.

### Standard headers

Each webhook request will include the following headers. The system headers will take precedence over any headers defined in the Admin UI.

| Header name | Description |
|  --- | --- |
| `Norce-Event-Message-Id` | A unique identifier for the event |
| `Norce-Event-Type` | The type of event, for example `CustomerChangedNotification`. [More info](/api-reference/schemas/event) |
| `Norce-Event-Timestamp` | Timestamp in ISO-8601 timestamp including timezone, like '2025-11-16T07:32.28.326837+01:00' |


### Code examples

Here is some examples on how to receive and use the event messages from Norce Webhooks.

details
summary
Example in C#

```csharp
[ApiController]
[Route("receiver")]
public class EventReceiver: ControllerBase
{
    [HttpPost]
    public IActionResult ReceiveEvent([FromBody] JObject eventPayload)
    {
        var eventId = Request.Headers["Norce-Event-Message-Id"];
        var eventType = Request.Headers["Norce-Event-Type"];
        var eventTimestamp = DateTime.Parse(Request.Headers["Norce-Event-Timestamp"]);

        // handle event

        Console.WriteLine($"Received event message: {eventId} of type {eventType} at {eventTimestamp}");

        return Accepted();
    }
}
```

details
summary
Example in Javascript/Express

```javascript
import express from "express";

const app = express();
const port = 7412;

app.use(express.json())

// Defining a route, must match the URL in the Admin UI
app.post('/receiver', (req, res) => {
    let eventPayload = req.body;
    let eventId = req.header("Norce-Event-Message-Id");
    let eventType = req.header("Norce-Event-Type");
    let eventTimestamp = new Date(req.header("Norce-Event-Timestamp"));
    // handle event

    console.log(`Received event message: ${eventId} of type ${eventType} at ${eventTimestamp}`);
    
    res.sendStatus(202);
});

// Starting the server
app.listen(port, () => {
    console.log(`Server is listening at http://localhost:${port}`);
});
```

## Monitoring events

In the Admin UI you can see a log of all events for each specific type and the status returned from the endpoint. The log is saved for 7 days. Expand the item
to se the event body.

## Common practice

### Refine the event settings for Notifications

Make sure to minimize the risk of noise in the event process, by defining only the rules you need on the event setting. If your target system only care about
some few product fields, make sure not to listen to other things in the event setting. Read more about [Event Settings](/developer-portal/system-integration/norce-event-settings) and the
`EntityChanged` property.

## Suggested further reading

- [System integration patterns](/developer-portal/system-integration/system-integration-patterns)
- [Calling Norce Commerce Query](/developer-portal/system-integration/calling-norce-commerce-query)
- [Calling Norce Commerce Connect](/developer-portal/system-integration/calling-norce-commerce-connect)