> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/value-stream-modeller/settings-and-configuration/events/events-authentication-and-configuration.md).

# Events Authentication and Configuration

Value Stream Modeller uses CloudEvents specifically with HTTP Protocol Binding and Binary Content Mode, where currently we support application/JSON only as a content-type for the data payload.

The CloudEvents should be used if you want third party systems to send trigger events to VSM. If you want to use triggers directly from Celonis, see the [Retrieving Data from Celonis](/value-stream-modeller/value-stream-designer/celonis-data-flow/retrieving-data-from-celonis.md) documentation.

CloudEvents is a specification for describing event data in a common way. It provides a structured format for event data and includes essential metadata such as the event type, source, and timestamp. HTTP Protocol Binding in CloudEvents defines how to use HTTP for transporting event data, and Binary Content Mode specifies how to encode the event in a binary format within the HTTP message.

{% hint style="info" %}
To learn more about CloudEvents, see:

* [CloudEvents](https://cloudevents.io/?mc_phishing_protection_id=164867-cgvppu0ukimc2q6i148g)
* [HTTP Protocol Binding for CloudEvents](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md)
* [CloudEvents spec](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#context-attributes)
  {% endhint %}

## Configuring the connection between the event and VSM execution

In VSM, an event-receiver serves as an endpoint specifically designed to receive external events, which are then used for initializing or resuming value stream. These events, for example a placement of a new order, are configured and transmitted to the receiver, subsequently triggering the corresponding processes within VSM.

To ensure that VSM can receive events, the initial step is to establish the connection and verify that authentication functions properly. This connection requires specific VSM tenant data, including the endpoint's source and secret values. These values are then utilized, for instance, in the Postman setup for development to ensure that requests are directed to the correct VSM tenant.

Once the connection is established and authenticated, you can start with creating a relevant event within VSM. This sequential process ensures smooth communication and accurate event handling between systems.

<figure><img src="/files/up6QvQkhxFXoBqR1kSwi" alt="Diagram of event-receiver connection flow to VSM"><figcaption><p>Overview of establishing a connection between an external event source and the VSM event-receiver endpoint</p></figcaption></figure>

To establish the connection between the event-receiver endpoint and VSM:

1. Go to **VSM** → **Admin** → **Settings**.
2. Use the **Source** and **Secret** values for postman environment configuration.

VSM:

<figure><img src="/files/GH5i7FSzY70nQT6SwxSr" alt="VSM Admin Settings with Event-Receiver Endpoint Source and Secret"><figcaption><p>The Admin Settings tab showing the Event-Receiver Endpoint Source and Secret values used for CloudEvents authentication</p></figcaption></figure>

Postman:

<figure><img src="/files/maY49rTNr4nMRab2MrgW" alt="Postman environment variables for src, secret, and hmac"><figcaption><p>Postman environment configured with src, secret, and hmac variables copied from VSM Admin settings</p></figcaption></figure>

**Source** - the attribute that defines the endpoint that is be used for sending an event to VSM, it’s unique for every tenant.\
If the endpoint is: `https://signals.emporix.io/e/{{src}}`, your `src` value is the value as in the source field in VSM.

<figure><img src="/files/GsUOwlgxtFQYJjI87sVy" alt="Postman request URL with src environment variable"><figcaption><p>The Postman request URL using the src variable from the environment to target the event-receiver endpoint</p></figcaption></figure>

**Secret** - an HMAC (keyed-Hash Message Authentication Code) secret; an HMAC is a type of authentication technique that uses a hash function and a secret key. You can use it to sign a request with a shared secret. It verifies if data is correct and authentic. In this configuration the hmac secret is a value for the `x-emporix-hmac` header.

<figure><img src="/files/kcyp1YPwQrsafon0vFLG" alt="Postman request headers with x-emporix-hmac"><figcaption><p>CloudEvents headers in Postman, including the x-emporix-hmac header for request authentication</p></figcaption></figure>

The header attributes are defined by the CloudEvents specification and are mandatory for sending the requests:

* `ce-source` - Represents the source of the event, providing information about where the event originated. The `ce-source` attribute typically contains a URI identifying the event producer or the endpoint that generated the event.
* `ce-type` - Represents the type of the event, providing information about the kind of event that occurred. The `ce-type` attribute typically contains a string value that identifies the specific type or category of the event, such as `order.created` or `payment.processed`. The `ce-type` events are the ones that refer the VSM tenant [events](/value-stream-modeller/value-stream-designer/process-components.md).
* `ce-specversion` - Represents the version of the CloudEvents specification with which the event is compliant. The `ce-specversion` attribute typically contains a string value indicating the version of the CloudEvents specification being used, such as "1.0" or "1.1".
* `ce-id` - Represents the unique identifier for the event instance. The `ce-id` attribute typically contains a string value that serves as a globally unique identifier (GUID) or a Universally Unique Identifier (UUID) for the event.

<figure><img src="/files/NTpuJEA77dV1oEvSHfkt" alt="Postman Pre-request Script generating HMAC signature"><figcaption><p>Pre-request Script that generates the HMAC signature from the request payload and secret environment variable</p></figcaption></figure>

**The signature has to be added in the request that is sent**. You can use the following sample to see how to generate the signature

* The `request.data` is the payload.\
  VSM is schemaless, the payload can be empty or it can be in any valid JSON format.
* The **secret** is the one that you need to copy from the Management Dashboard admin settings.

## Request Examples

Here's an example of a request to generate a signature:

```javascript
var sha256digest = CryptoJS.HmacSHA256(request.data, "the-secret-from-management-dashboard");
var base64sha256 = CryptoJS.enc.Base64.stringify( sha256digest);
postman.setEnvironmentVariable("hmac", base64sha256);
```

<details>

<summary>See an example of a postman environment</summary>

```json
{
	"id": "0c29dar5-13er-4766-82f8-91e87a45ghy6",
	"name": "devenv",
	"values": [
		{
			"key": "src",
			"value": "src_w34a44rft567",
			"type": "default",
			"enabled": true
		},
		{
			"key": "secret",
			"value": "<replace with secret from VSM->Admin->Events in Management Dashboard>",
			"type": "secret",
			"enabled": true
		},
		{
			"key": "hmac",
			"value": "",
			"type": "any",
			"enabled": true
		}
	],
	"_postman_variable_scope": "environment",
	"_postman_exported_at": "2023-04-19T07:26:28.294Z",
	"_postman_exported_using": "Postman/10.10.4"
}

```

</details>

<details>

<summary>See an example of a postman collection</summary>

```json
{
	"info": {
		"_postman_id": "d5ce7aff-7f71-4261-b369-7cd67813e878",
		"name": "VSM Hello World",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
		"_exporter_id": "12223042"
	},
	"item": [
		{
			"name": "say-hello",
			"event": [
				{
					"listen": "prerequest",
					"script": {
						"exec": [
							"var sha256digest = CryptoJS.HmacSHA256(request.data, postman.getEnvironmentVariable(\"secret\"));",
							"var base64sha256 = CryptoJS.enc.Base64.stringify( sha256digest);",
							"postman.setEnvironmentVariable(\"hmac\", base64sha256);"
						],
						"type": "text/javascript"
					}
				}
			],
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "ce-source",
						"value": "postman",
						"type": "text"
					},
					{
						"key": "ce-type",
						"value": "hello_world",
						"type": "text"
					},
					{
						"key": "ce-specversion",
						"value": "1.0",
						"type": "text"
					},
					{
						"key": "ce-id",
						"value": "{{$guid}}",
						"type": "text"
					},
					{
						"key": "x-emporix-hmac",
						"value": "{{hmac}}",
						"type": "text"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\n    \"hello\" : \"world\"\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "https://signals.emporix.io/e/{{src}}",
					"protocol": "https",
					"host": [
						"signals",
						"emporix",
						"io"
					],
					"path": [
						"e",
						"{{src}}"
					]
				}
			},
			"response": []
		}
	]
}
```

</details>

## Creating a new event

Once the connection setup is complete, you can proceed to create a new event. Ensure that the name of the event you create corresponds to the event used in Postman's POST request.

Utilize the `ce-type` attribute to recognize events and provide information indicating that the event has occurred. By aligning the event configured in VSM with the `ce-type` name, you ensure that information about events is accurately received and processed. This alignment facilitates seamless communication and data handling between VSM and Postman.

To create a new event:

1. Go to **VSM** -> **Admin** -> **Events**.
2. Choose **Create New Event**.
3. Specify the **Display** and **Event** names.
   * **Display name** is the name that is visible in the UI when you create an execution template, for example: Order Created.
   * **Event name** is the name of the registered event, for example: `emporix/dcp/order.created`.
4. Save your changes.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.emporix.io/value-stream-modeller/settings-and-configuration/events/events-authentication-and-configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.