> For the complete documentation index, see [llms.txt](https://developers.didomi.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.didomi.io/api-and-platform/widgets/privacy-widgets/headless-widgets/custom-events.md).

# Custom events

Custom events are *synthetic events* in Javascript that can be dispatched to our SDK.

Use custom events to communicate with Didomi custom elements to wrap your code and handle all logic, analytics and API requests.

* [didomi:send-authentication](#didomi-send-authentication)
* [didomi:verify-otp-code](#didomi-verify-otp-code)
* [didomi:set-pending-consents](#didomi-set-pending-consents)
* [didomi:save-pending-consents](#didomi-save-pending-consents)
* [didomi:set-consents](#didomi-set-consents)

#### didomi:send-authentication

To request end-user authentication through the Didomi SDK and send an email to your end-user (via either Magic Link or One-Time Password code) dispatch the `didomi:send-authentication` custom event. Set the email address provided by the end-user to `detail.value`.

Note that our Headless widget will use the default authentication provider of your organization. To use a different provider, you can [define a provider](/api-and-platform/widgets/privacy-widgets/authentication/manage-authentication-providers.md#manage-authentication-within-a-widget) at widget level.

{% hint style="warning" %}
`didomi:send-authentication` custom event needs to be dispatched from an element within the `didomi-auth-headless` custom element.
{% endhint %}

```javascript
new CustomEvent("didomi:send-authentication", {
      detail: {
        value: email,
      },
      bubbles: true,
      composed: true,
    });
```

#### didomi:verify-otp-code

*<mark style="color:blue;">This event needs the previous event to work properly as the</mark>* <mark style="color:blue;">`send-authentication`</mark> *<mark style="color:blue;">event will allow email address storage in local storage that is required to verify the code.</mark>*

If your widget is using a One-Time Password provider, you need to verify the code received by the end-user. To verify the code, dispatch the `didomi:verify-otp-code` custom event. Set the code provided by the end-user to `detail.value`.

{% hint style="warning" %}
`didomi:verify-otp-code` custom event needs to be dispatched from an element within the `didomi-auth-headless` custom element.
{% endhint %}

```json
new CustomEvent("didomi:verify-otp-code", {
      detail: {
        value: otpCode,
      },
      bubbles: true,
      composed: true,
    });
```

#### didomi:set-pending-consents

To set end-user pending consents in your web application state, dispatch the `didomi:set-pending-consents` custom event.

When setting a purpose, the `detail` object must contain the `purposeId` and the corresponding `value` (true or false). When setting a preference, the `detail` object must contain the `purposeId`, `preferenceId`, and the selected `value`.

{% hint style="warning" %}
Custom event `didomi:set-pending-consents` should be dispatched from an element placed within the `didomi-pending-consent-receiver` wrapper.
{% endhint %}

```javascript
new CustomEvent("didomi:set-pending-consents", {
      // If used for Purposes
      detail: {
        purposeId,
        value: true/false,
      },
      // If used for Preference values
      detail: {
        purposeId,
        preferenceId,
        value: "asdf,ghjk,bvcx", // list of enabled values as string
      },
      bubbles: true,
      composed: true,
    });
```

#### didomi:save-pending-consents

To save end-user pending consents using the Didomi SDK, dispatch the `didomi:save-pending-consents` custom event.

{% hint style="warning" %}
Custom event `didomi:save-pending-consents`should be dispatched from an element placed within the `didomi-pending-consent-receiver` wrapper.
{% endhint %}

```javascript
new CustomEvent("didomi:save-pending-consents", {
      detail: {
        // You can pass optional metadata object
        metadata: {},
        // You can pass optional userMetadata object
        userMetadata: {},
      },
      bubbles: true,
      composed: true,
    });
```

#### didomi:set-consents

To save end-user consent upon end-user click through our SDK, dispatch the `didomi:set-consents` custom event.

When saving a purpose, the `detail` object should include the `purposeId` and the corresponding `value` (true or false). When saving a preference, the `detail` object should include the `purposeId`, `preferenceId`, and the selected `value`.

Custom event `didomi:set-consents` should be dispatched from an element placed within the `didomi-consent-receiver` wrapper.

```javascript
new CustomEvent("didomi:set-consents", {
      // If used for Purposes
      detail: {
        purposeId,
        value: true/false,
        // You can pass optional metadata object
        metadata: {},
        // You can pass optional userMetadata object
        userMetadata: {},
      },
      // If used for Preference values
      detail: {
        purposeId,
        preferenceId,
        value: "qFkQbPnT,gEhjHDk,sbvLLcx", // list of enabled values as string
        // You can pass optional metadata object
        metadata: {},
        // You can pass optional userMetadata object
        userMetadata: {},
      },
      bubbles: true,
      composed: true,
    });
```

*Note that the* `bubbles` *and* `composed` *options must be set to* `true` *to allow the event to bubble and trigger listeners outside of a shadow root, respectively.*


---

# 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://developers.didomi.io/api-and-platform/widgets/privacy-widgets/headless-widgets/custom-events.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.