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:

Event configurations

For every event type you want to listen for, you need to activate them in the Admin UI here.

Configurations in the Admin UI

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.

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 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.

Code examples

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

[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();
    }
}

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 om other things in the event setting. Read more about Event Settings and the EntityChanged property.

Suggested further reading

• System integration patterns
• Calling Norce Commerce Query
• Calling Norce Commerce Connect