> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# $wsAsse - Asynchronous HTTP events (ASSE)

> Trigger preconfigured server-side events that send HTTP requests to external URLs in the background – e.g. for tracking, webhooks, and third-party systems.

With the `$wsAsse` module, you trigger [**ASSE events**](/en/glossar#asse) (Asynchronous Server-Side Events) from within a template. An event sends an HTTP request in the background to an external URL defined in the configuration in order to transmit data to an external service (e.g. tracking after an order).

This page is about triggering preconfigured events from the template. How an event is set up (target URL, HTTP method, retries, success conditions) is described in the [ASSE configuration](/en/konfiguration/general-allgemeine-shopeinstellungen#4-general-asse-schnittstelle-für-asynchronous-server-side-events-asse).

***

## Prerequisite

Before `$wsAsse` has any effect in the template, at least one event must be created in the configuration. Without a configured event, there is no event ID you could trigger, and [`fire()`](#wsasse-fire) returns `false`.

The [configuration](/en/konfiguration/general-allgemeine-shopeinstellungen#4-general-asse-schnittstelle-für-asynchronous-server-side-events-asse) defines which URL is called, which HTTP method is used, how often retries are performed on errors, and under what conditions a request is considered successful.

***

## Basic concept

An ASSE event always follows the same flow: configure event → trigger in the template → request runs asynchronously in the background.

You set up an event once in the configuration and give it an ID. In the template, you then trigger it via [`fire()`](#wsasse-fire) using this ID and optionally pass data along. The shop then sends the HTTP request automatically in the background.

### Asynchronous: return value does not equal success

`fire()` returns true as soon as the event is validly configured and the request has been queued. However, this does not mean that the external server has processed the request successfully. Since ASSE sends requests asynchronously, the actual execution happens with a time delay. Therefore, do not rely on the return value to verify the success of the external processing.

### Triggering during page rendering

`fire()` is executed when the template is rendered, that is, on every call of the corresponding page. Therefore place the call only on the relevant page (e.g. the order confirmation) and keep in mind: if the customer reloads the page, the event is triggered again. For count-relevant events (e.g. tracking), make sure that triggering again does not cause any problems.

### Passing data

ASSE appends the optional second parameter `data` to the URL or sends it in the request body, depending on the HTTP method. Two points are important so that the data arrives correctly:

* The value is not automatically URL-encoded. If it contains special characters, encode it yourself.
* If you pass a list or an object, the value is automatically converted into a JSON object.

***

## Module overview

**Example / excerpt of** `$wsAsse`

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{= $wsAsse | json }}
```

**JSON output**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "asseConfigs": [...],
  "fire": "ƒ()"
}
```

Note: `"ƒ()"` denotes a function (method).

**Variables and methods overview**

| **Name**      | **Return type** | **Description**                                    |
| ------------- | --------------- | -------------------------------------------------- |
| `asseConfigs` | array           | List of all configured events with their settings. |
| `fire()`      | bool            | Triggers a preconfigured event.                    |

***

## Variables

### \$wsAsse.asseConfigs

Returns a list of all configured events with their settings. Use it to check which events (and therefore which event IDs) are available before triggering one. If the list is empty (`[]`), no event is configured. The events are created in the [configuration](/en/konfiguration/general-allgemeine-shopeinstellungen#4-general-asse-schnittstelle-für-asynchronous-server-side-events-asse).

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{= $wsAsse.asseConfigs | json }}
```

***

## Methods

### \$wsAsse.fire()

Triggers a preconfigured event. In the background, an HTTP request is sent to the URL stored in the configuration. Via the second parameter, you can optionally pass data for the current operation. Depending on the HTTP method, this data is appended to the URL or sent in the request body.

**Signature**\
`$wsAsse.fire(eventId, data)`

**Return value**\
`bool` - `true` if the event is validly configured and has been triggered, `false` in case of a configuration problem, for example when the `eventId` does not match any configured event. Note the [asynchronous behavior](#asynchronous-return-value-does-not-equal-success): `true` says nothing about the success of the external request.

**Parameters**

| **Name**  | **Type** | **Required** | **Description**                                                                        |
| --------- | -------- | ------------ | -------------------------------------------------------------------------------------- |
| `eventId` | string   | yes          | ID of the event to be triggered. Must correspond to a valid ID from the configuration. |
| `data`    | string   | no           | Additional data to be sent with the request (see [Passing data](#passing-data)).       |

**Example** that triggers a preconfigured event `myevent` with the user ID:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $eventData = "userid=" + $wsAccount.id }}
{{ $wsAsse.fire('myevent', $eventData) }}
```

<Info>
  \$wsAccount.id comes from the [\$wsAccount](/en/frontend/referenz/module/wsAccount) module and returns the ID of the logged-in customer.
</Info>

***

## Examples

### Trigger Awin tracking on the order confirmation page

A common use case is sending tracking data to an external service provider after a successful order. This example assembles the order data (order number, goods value, currency) from [\$wsCheckout](/en/frontend/referenz/module/wscheckout) into a parameter string and uses it to trigger the `awintracking` event.

Since this call fires on every page rendering (see [Triggering during page rendering](#triggering-during-page-rendering)), it belongs exclusively on the order confirmation page.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $eventData = "&merchant=12345" }}
{{ var $eventData = $eventData + "&amount=" + $wsCheckout.sum.totalNet }}
{{ var $eventData = $eventData + "&ch=aw" }}
{{ var $eventData = $eventData + "&parts=DEFAULT:" + $wsCheckout.sum.totalNet }}
{{ var $eventData = $eventData + "&cr=" + $wsCheckout.sum.currency }}
{{ var $eventData = $eventData + "&ref=" + $wsCheckout.orderId }}
{{ var $eventData = $eventData + "&testmode=0" }}

{{ if $wsVoucher.vouchers[0] }}
  {{ var $eventData = $eventData + "&vc=" + $wsVoucher.vouchers[0].id }}
{{ /if }}

{{ $wsAsse.fire('awintracking', $eventData) }}
```

For this, an event with the ID `awintracking` must be created in the configuration that points to the Awin tracking URL. `merchant=12345` is a placeholder and must be replaced with your Awin merchant ID.

**Result** After the order confirmation page has been rendered, the tracking request is sent to Awin in the background.

***

## Related links

* [ASSE configuration](/en/konfiguration/general-allgemeine-shopeinstellungen#4-general-asse-schnittstelle-für-asynchronous-server-side-events-asse) – defines the target URL, HTTP method, retries, and success conditions of an event. Prerequisite for `fire()` to have any effect.
* [\$wsCheckout](/en/frontend/referenz/module/wscheckout) – provides the order data passed in the tracking example.
* [\$wsAccount](/en/frontend/referenz/module/wsAccount) – provides the user ID used in the simple example.

With the `$wsAsse` module, you trigger [**ASSE events**](/en/glossar#asse) (Asynchronous Server-Side Events) from within a template. An event sends an HTTP request in the background to an external URL defined in the configuration in order to transmit data to an external service (e.g. tracking after an order).

This page is about triggering preconfigured events from the template. How an event is set up (target URL, HTTP method, retries, success conditions) is described in the [ASSE configuration](/en/konfiguration/general-allgemeine-shopeinstellungen#4-general-asse-schnittstelle-für-asynchronous-server-side-events-asse).

Before `$wsAsse` has any effect in the template, at least one event must be created in the configuration. Without a configured event, there is no event ID you could trigger, and [`fire()`](#wsasse-fire) returns `false`.

## Basic concept

An ASSE event always follows the same flow: configure event → trigger in the template → request runs asynchronously in the background.

You set up an event once in the configuration and give it an ID. In the template, you then trigger it via [`fire()`](#wsasse-fire) using this ID and optionally pass data along. The shop then sends the HTTP request automatically in the background.

### Asynchronous: return value does not equal success

`fire()` returns `true` as soon as the event is validly configured and the request has been queued. However, this does not mean that the external server has processed the request successfully. Since ASSE sends requests asynchronously, the actual execution happens with a time delay. Therefore, do not rely on the return value to verify the success of the external processing.

### Triggering during page rendering

`fire()` is executed when the template is rendered, that is, on every call of the corresponding page. Therefore place the call only on the relevant page (e.g. the order confirmation) and keep in mind: if the customer reloads the page, the event is triggered again. For count-relevant events (e.g. tracking), make sure that triggering again does not cause any problems.

### Passing data

ASSE appends the optional second parameter `data` to the URL or sends it in the request body, depending on the HTTP method. Two points are important so that the data arrives correctly:

* The value is not automatically URL-encoded. If it contains special characters, encode it yourself.
* If you pass a list or an object, the value is automatically converted into a JSON object.

***

Note: `"ƒ()"` denotes a function (method).

| **Name**      | **Return type** | **Description**                                    |
| ------------- | --------------- | -------------------------------------------------- |
| `asseConfigs` | array           | List of all configured events with their settings. |
| `fire()`      | bool            | Triggers a preconfigured event.                    |

Returns a list of all configured events with their settings. Use it to check which events (and therefore which event IDs) are available before triggering one. If the list is empty (`[]`), no event is configured. The events are created in the [configuration](/en/konfiguration/general-allgemeine-shopeinstellungen#4-general-asse-schnittstelle-für-asynchronous-server-side-events-asse).

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{= $wsAsse.asseConfigs | json }}
```

Triggers a preconfigured event. In the background, an HTTP request is sent to the URL stored in the configuration. Via the second parameter, you can optionally pass data for the current operation. Depending on the HTTP method, this data is appended to the URL or sent in the request body.

**Return value**\
`bool` - `true` if the event is validly configured and has been triggered, `false` in case of a configuration problem, for example when the `eventId` does not match any configured event. Note the [asynchronous behavior](#asynchronous-return-value-does-not-equal-success): `true` says nothing about the success of the external request.

| **Name**  | **Type** | **Required** | **Description**                                                                        |
| --------- | -------- | ------------ | -------------------------------------------------------------------------------------- |
| `eventId` | string   | yes          | ID of the event to be triggered. Must correspond to a valid ID from the configuration. |
| `data`    | string   | no           | Additional data to be sent with the request (see [Passing data](#passing-data)).       |

**Example** that triggers a preconfigured event `myevent` with the user ID:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $eventData = "userid=" + $wsAccount.id }}
{{ $wsAsse.fire('myevent', $eventData) }}
```

<Info>
  \$wsAccount.id comes from the [\$wsAccount](/en/frontend/referenz/module/wsAccount) module and returns the ID of the logged-in customer.
</Info>

A common use case is sending tracking data to an external service provider after a successful order. This example assembles the order data (order number, goods value, currency) from [\$wsCheckout](/en/frontend/referenz/module/wscheckout) into a parameter string and uses it to trigger the `awintracking` event.

Since this call fires on every page rendering (see [Triggering during page rendering](#triggering-during-page-rendering)), it belongs exclusively on the order confirmation page.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $eventData = "&merchant=12345" }}
{{ var $eventData = $eventData + "&amount=" + $wsCheckout.sum.totalNet }}
{{ var $eventData = $eventData + "&ch=aw" }}
{{ var $eventData = $eventData + "&parts=DEFAULT:" + $wsCheckout.sum.totalNet }}
{{ var $eventData = $eventData + "&cr=" + $wsCheckout.sum.currency }}
{{ var $eventData = $eventData + "&ref=" + $wsCheckout.orderId }}
{{ var $eventData = $eventData + "&testmode=0" }}

{{ if $wsVoucher.vouchers[0] }}
  {{ var $eventData = $eventData + "&vc=" + $wsVoucher.vouchers[0].id }}
{{ /if }}

{{ $wsAsse.fire('awintracking', $eventData) }}
```

For this, an event with the ID `awintracking` must be created in the configuration that points to the Awin tracking URL. `merchant=12345` is a placeholder and must be replaced with your Awin merchant ID.

**Result** After the order confirmation page has been rendered, the tracking request is sent to Awin in the background.

***

## Related links

* [ASSE configuration](/en/konfiguration/general-allgemeine-shopeinstellungen#4-general-asse-schnittstelle-für-asynchronous-server-side-events-asse) – defines the target URL, HTTP method, retries, and success conditions of an event. Prerequisite for `fire()` to have any effect.
* [\$wsCheckout](/en/frontend/referenz/module/wscheckout) – provides the order data passed in the tracking example.
* [\$wsAccount](/en/frontend/referenz/module/wsAccount) – provides the user ID used in the simple example.