Skip to main content

Event exports

EVA supports bidirectional communication; sometimes, pulling data alone is just not the right fit for your integration. 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.

In-depth event exports docs

This documentation page is aimed at setting up your event export configuration in Admin Suite, which takes the cake when it comes to ease of use. If you like to get in-depth knowledge about event exports however, such as best practices, please see our API Event exports documentation.

Creating your event export configuration​

The chapter's overview shows you all current event export configurations and their status.

Permission

In order to view (and/or manage) this chapter, the permission EventExportConfiguration is required with the View scope. For info on setting permissions, see Employees in Admin Suite.


General information​

When creating a new configuration, you first have to specify its basic details:

  • Name
  • Status - whether you want it to be active straightaway
  • Endpoint - your (middleware) endpoint for EVA to send the events to
Endpoints for testing

For testing purposes we advise using PipeDream.

Select HTTP / Webhook API, followed by Trigger. Set it to Full HTTP request and combine it with Return HTTP 200 OK The URL for your testing endpoint will be displayed which you can use in your configuration in Admin Suite.

Configuration​

Its Configuration card has several options, including the setup of your security measures.

  • Authorization type: this choice presents your level of security. It's important because you do not want your endpoint to accept events from just any sender, allowing just about anyone to for example transmit you a Confirmed event for a payment.
    • None: to be used only for testing purposes
    • Bearer token: a token as registered by you from New Black or vice versa - sent out as Authorization: Bearer {token}
    • Static unschemed token: an unschemed (without Bearer or similar) token - sent out as Authorization: {token}
  • Response mode: this defines how EVA needs to interpret your endpoint's responses.
    • Loose: use this if you want EVA to interpret any response containing a 2xx status as a successful response
    • Normal: your endpoint will have to respond with a 200 (OK) response with a string type body *[ACK] for EVA to acknowledge it as being a succesful response - if not: EVA will retry the event
  • Include/Exclude organization units: these can be used standalone or in a combination.
    • By leaving it empty: events will be exported for all possible OUs (keep in mind that doing so can lead to performance-impacting amounts of exports)
    • Specifying included OUs: events will only be exported for these (underlying) outages
    • Specifying excluded OUs: events for all OUs except these
    • Included and excluded OUs: events for all included OUs minus the excluded operations
  • ScriptID: the EventExport extension point allows you to create detailed filters for when to send off webhooks. You can add the ID of existing EventExport scripts here.
  • Timeout seconds: you can specify an amount of time during which EVA may expect a response from your middleware.
    • Regardless of your input, EVA maintains a hard cut-off time of 5000 ms (5 seconds). Any longer than that and your entire operation will struggle with these delays
    • Strive for < 200 ms

Message types​

Now that you've got your endpoint configured, it's time to instruct EVA on what kind of events you want to export to the endpoint.

You can add one Event export target with one Event type at a time. You can however add as many combinations as you like.

Multiple Endpoints

There's no limit to the amount of endpoint configurations you can create and we advise you to make use of that. Create configurations. with dedicated endpoints. for all your critical business processes. This will minimize the chance of delays whenever there are large amounts of webhooks fired off by EVA.

That is all for the basics of setting up an event export configuration in Admin Suite. There is however a lot more to it, such as testing, troubleshooting and the option to replay events. These are all available in the mentioned API Event exports documentation.