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, enable event exports for your environment with the following setting.
EventExports:Enabled
- true
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:
{
"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
}
}
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"
}
]
}
}
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]
}
}
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
.