Event export basics

Sometimes, pulling data alone is just not the right fit for your integration, which is why EVA supports bidirectional communication. For instance, when you want to trigger a workflow when an order is paid, or send out emails when a shipment is sent. Event exports ("webhooks") provide a valuable toolset for integrations to achieve this.

Because EVA is a real-time, event-based platform, we export these updates in real-time. When you look at the fundamentals, it's just a matter of specifying the endpoint to which the updates should be routed and you're all set.

These event exports themselves are of a simple nature and CANNOT be altered to include more information. If additional data is required after receiving an export, you can use services such as GetOrder based on the ID as specified in the export.

Event export basics

Let's start you off with the basics of event exports: our main differentiators for event messages and the information the messages can include.

Event contents

The event export contains a bunch of identifiers, with our two main differentiators being Target and EventType. These two properties determine the nature of the event export.

Target can be seen as the subject of the event export
EventType then defines what has happened for the Target

To make this clearer with an example: a Target can be Order, with Type being Created or Shipped.

A complete list of the possible targets and their respective event types can be on its dedicated page Targets and types.

Properties

Along with the two main identifiers, the body of the event contains the following properties:

Property	Type	Description
UID	`String`	Unique identifier for the event.
CreationTime	`String`	Time at which the event was created in UTC (in ISO8601 format).
Timezone	`String`	Timezone in which the event was created.
Target	`String`	Event subject.
EventType	`String`	Actual event for the target.
Identifier	`String`	The Target's EVA ID.
BackendID	`String`	The target's Backend ID.
BackendSystemID	`String`	The ID of the system where the BackendID originated from, ensuring a unique combination.
Data	`Object`	Additional data for the event. This will always be an object. However, the properties may vary, please see the example events below.
IsSystemGenerated	`String`	This is one of the common properties in the Data object, showing if an order is an order generated by EVA itself to mirror an existing sales or purchase order in POSO or SOPO flows.

Event export configurations

Now that we've got you covered on the principles of our event exports, it's time to jump into event export configurations.

Settings

First off, we've got two settings that enable event exports for your environment.

Title	Value	Description
EventExports:Enabled	true	This setting enables event exports in general
EventExports:EnableEventExportConfigurations	true	This additional setting unlocks the use of multiple endpoints

Unlocking multiple endpoints for existing environments

Most existing environments (pre-core 2.0.678) run solely on EventExports:Enabled, which limits you to a single endpoint. Although we do recommend you to diversify your endpoints, enabling the EventExports:EnableEventExportConfigurations setting for existing environments requires additional work by New Black. Please contact your TL to get this up and running for you.

Services

We provide a set of services that can be used for event export configuration.

The most basic form of event export configuration is configured as follows:

CreateEventExportConfiguration
{
  "Name": "BasicEventExportConfiguration",
  "Status": "1",
  "Endpoint": "https://hookb.in/je0Zbx07Wdt9dlMMmnzZ",
  "Config": {
      "ResponseMode": 1
  }
}

This simple configuration only specifies an endpoint. This will receive all possible event exports, does not require authentication and does not care about the contents of your response message.

Status

Status indicates whether or not the configuration should be used:

ResponseMode

The response mode specifies what response EVA should expect when firing off webhooks towards this configuration:

Authorization

Your event exports contain an authorization object, which can work with one of three kinds of authorization based on your preferences:

A StaticBearerToken (as specified by you, or us);
A StaticUnschemedToken;
A Certificate.

Whatever you choose, EVA will use it as authentication towards the specified endpoint.

{
  "Config": {
    "Authorization": {
      "StaticBearerToken": "",
      "StaticUnschemedToken": "",
      "ClientCertificate":{
         "Certificate": "<base64-string-of-the-actual-certficate>",
         "Password": "<password-to-the-certificate>"
}
    },
    "ResponseMode": 1
  }
}

Certificate requirements

The client certificate that can be used for mTLS must be X509 in PKCS12 format. Also, it may not be expired, must have a private key and have clientAuth in it's extended key usage.

If you want to make use of a certificate file we recommend doing so via the UI in Admin Suite, please see Event exports configuration for more information.

Event specification

In the MessageTypes object we can specify what messages we want to export to the endpoint.

Leaving it empty will export all possible event types;
You can exclude event types by using ExcludedMessageTypes;
By specifying TargetID, EVA will send all EventTypes for that target.

As a reminder, using this kind of filtering for your endpoint keeps it running smoothly.

{
  "Config": {
    "MessageTypes": [
      {
        "TargetID": 1, // 1 = order
        "EventType": "created"
      }
    ]
  }
}

Using both MessageTypes and ExcludedMessageTypes

When specifying both MessageTypes and ExcludedMessageTypes, the result is MessageTypes minus ExcludedMessageTypes.

OU specification

In the IncludeOrganizationUnits object we can specify for what OU we want to export events to the endpoint. Leaving it empty will export the events for all possible OUs. To exclude OUs, use ExcludeOrganizationUnits instead.

{
  "Config": {
    "IncludeOrganizationUnits": [1, 2, 3]
  }
}

Using both IncludeOrganizationUnits and ExcludeOrganizationUnits

When specifying both IncludeOrganizationUnits and ExcludeOrganizationUnits, the result is IncludeOrganizationUnits minus ExcludeOrganizationUnits.

Additional services

There are five more related and straight-forward services similar to CreateEventExportConfiguration.

Relevant services

Endpoint requirements

Aside from configuring your event export within EVA, you need to ensure your endpoint is capable of communicating with EVA. Please take the following into account:

Your endpoint needs to respond with 200 (OK) response, with a string body [ACK]. If this is not the case, the event will retry.
Make sure Endpoint (or any intermediate redirect routes) does not resolve to any RFC1918 (in other words: local) addresses.
Make sure Endpoint uses the HTTPS protocol which is as up to date as possible - preferrably HTTP/3
Endpoint should be accessible from EVA
Webhook should accept a POST request on endpoint
Implement authentication on the endpoint - use preferably both the aforementioned authorization and verification

Verifying the signature

Signature verification is an additional, optional layer of security to your event exports.

Each request to Endpoint will have the following headers:

X-EVA-Signing-1
X-EVA-Signing-2
X-Eva-Signing-Headers.

The latter will contain a comma-separated list of all request headers considered in the signing process. This is helpful when operating behind a reverse proxy that might add some headers. Make sure this proxy does not remove any headers, as this will render you unable to validate the requests.

To validate the requests, take the following three steps.

1. Hashing the headers

Only use the headers as specified in X-Eva-Signing-Headers

Transform the headers from this:

Content-Type: application/json;charset=utf-8
Content-Length: 12345
Authentication: Bearer MySecretToken

to:

Authentication=Bearer MySecretToken
Content-Length=12345
Content-Type=application/json;charset=utf-8

Sort the headers, first by header key, then by header value
Next make sure the header key and value are separated by a =
Also make sure the line breaks are \n

Then we transform this text to bytes (use UTF-8) and hash it using SHA256. Save the hash as a uppercase hexadecimal string.

2. Hashing the body

Hash the body using SHA256. Save the hash as a uppercase hexadecimal string.

3. Calculate the hash

Calculate the final hash as follows (store as uppercase hexadecimal string):

final_hash = sha256(header_hash + body_hash + api_key)

This hash should match either X-EVA-Signing-1 or X-EVA-Signing-2.

Event export basics

Event export basics​

Event contents​

Properties​

Event export configurations​

Settings​

Services​

Status​

ResponseMode​

Authorization​

Event specification​

OU specification​

Additional services​

Endpoint requirements​

Verifying the signature​

Event export basics

Event contents

Properties

Event export configurations

Settings

Services

Status

ResponseMode

Authorization

Event specification

OU specification

Additional services

Endpoint requirements

Verifying the signature