> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.drimify.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Setting up integrations in Drimify (Webhooks & Mailers)

## Setting Up Integrations in Drimify (Webhooks & Mailers)

Drimify integrations allow you to automatically send participant data to external services whenever a user interacts with your application. You can connect to a Custom API, HubSpot, or Salesforce — and for each integration, you can specify exactly which data fields are transmitted.

## Getting Started

| Go to My Account → Integrations.

If no integration has been configured yet, you will see the placeholder screen "No webhook integrations yet" or ""No mailer integrations yet".
Click **+ Add New Integration** (available both at the top right and in the center of the page) to open the integration selector.

# Webhook Integrations

## Selecting an Integration Type

A modal window titled **"Select Webhook Integration"** will appear.
You can filter by category using the dropdown menu (default is **All**). The three available integrations are:

* Custom API — for any REST API endpoint you control
* HubSpot — for CRM & Marketing automation through HubSpot
* Salesforce — for Salesforce CRM

Click the integration tile you want to configure.

# Custom API Integration

## Authentication

After selecting **Custom API**, the **Add Integration** panel opens with the following fields:

* **Integration Name**: A label for your own reference (default: "Custom API Integration"). You can rename it to something more descriptive.
* **API Endpoint**: The full URL of your webhook receiver (for example: `https://api.example.com/webhook`). This must be an HTTPS endpoint.
* **HTTP Method**: 

Select the HTTP method used to send the webhook request to your endpoint.
Available options:

* **POST** — Recommended for most use cases (creates a new resource or sends data)
* **PUT** — Fully replaces an existing resource
* **PATCH** — Partially updates an existing resource

Choose the method that matches how your API expects to receive data.

* **Authentication Type**: Choose the authentication method used by your endpoint.

| Option | Description |
| ---- |
| None | No authentication header is sent |
| API Key (X-API-KEY) | Sends the key in an `X-API-KEY` header |
| Bearer Token | Sends the key as `Authorization: Bearer <token>` |
| Basic Authentication | Sends an `Authorization: Basic` header built from your Login and Password |
| Custom Header | Lets you define your own header name (e.g. `X-Custom-Auth`) |

* When **Basic Authentication** is selected, two fields appear: **Login** (username) and **Password**. Enter them as-is — Drimify builds the `Authorization: Basic` header for you automatically. You do not need to encode anything yourself.
* When **Custom Header** is selected, an additional **Custom Header Name** field appears where you can enter the header key name.
* **API Key**: The secret value sent using the selected authentication method.
* **Verify Connection**: Click this button to test whether Drimify can successfully reach your endpoint using the provided credentials before saving.

## Fetching the token from an auth endpoint (pre-call)

Some APIs require you to authenticate first: you call an auth endpoint with your credentials, receive a token, and use that token on the actual webhook call. Drimify supports this automatically.

When the Authentication type is **API Key**, **Bearer Token**, or **Custom Header**, a checkbox **"Fetch this token from an auth endpoint"** appears. When checked, the static credential field is replaced by the pre-call settings below (for Custom Header, the header name field stays visible — the fetched token is sent in that header).

The fetched token is placed according to your Authentication type:

* Bearer Token → `Authorization: Bearer <token>`
* API Key → `X-API-KEY: <token>`
* Custom Header → `<your header name>: <token>`

### Choose one of three methods

**OAuth2 (client_credentials)** — for standard OAuth2 servers (e.g. Keycloak).

* Fields: **Token URL**, **Client ID**, **Client Secret**, **Scope** (optional)
* Drimify sends a standard OAuth2 client_credentials request and reads the token from `access_token`. The token lifetime is taken from the server's `expires_in`.

**Login JSON** — for login endpoints that take a JSON body and return a token.

* Fields: **Auth URL**, **Body** (key/value list), **Token path**
* Drimify sends a `POST` with a JSON body built from your key/value rows (e.g. rows `email = a@b.com` and `password = secret` produce `{"email":"a@b.com","password":"secret"}`).
* **Token path** tells Drimify where the token is in the JSON response, using dot notation — e.g. `data.access_token`, or just `token` if it is at the top level.

**Custom** — for anything that does not fit the two methods above.

* Fields: **Auth URL**, **HTTP method** (`POST` or `GET`), **Headers** (key/value list), **Body** (key/value list), **Body encoding** (JSON or form-urlencoded), **Token path**
* With method `GET`, there is no request body — pass parameters via the Headers or the Auth URL.
* If you add a `Content-Type` header yourself, it takes precedence over the one implied by the body encoding.

### Key/value lists (Body and Headers)

Each row has a **key**, a **value**, and a **"sensitive"** checkbox (checked by default). Rows can be added and removed, but not edited in place — to change a row, remove it and add it again. The sensitive flag can only be set when adding a row. Sensitive values are masked after saving and are never exposed again, in the form or in logs.

### Token caching and retries

* OAuth2 tokens are cached for the duration given by `expires_in`.
* For Login JSON and Custom, set **Token validity (minutes)** — default is **60 minutes** if left empty.
* Cached tokens are kept for a maximum of 7 days.
* If your endpoint returns **401** while a cached token is in use, Drimify discards the token, re-authenticates, and retries the call once.
* If the pre-call fails (error, timeout, or no token found at the Token path), the webhook is **not** sent unauthenticated — the delivery fails, is logged, and is retried by the delivery queue as usual.

### Verify Connection with a pre-call

The **Verify Connection** button fully supports the pre-call: it first authenticates against your auth endpoint, then runs the test call with the fetched token.

# HubSpot Integration

After selecting **HubSpot**, the panel displays:
* **Integration Name**: Default: "HubSpot Integration".
* **API Key / Access Token**: Paste your HubSpot Private App Access Token here. HubSpot deprecated legacy API keys in 2022, so you must use a Private App token generated from your HubSpot account under: **Settings → Integrations → Private Apps**
* **Verify Connection**: Tests the token against the HubSpot API before saving.

# Salesforce Integration

After selecting **Salesforce**, the panel displays:

* **Integration Name**: Default: "Salesforce Integration".
* **Salesforce Domain**: The URL of your Salesforce instance (for example: `yourcompany.my.salesforce.com`).
* **Consumer Key and Consumer Secret**: Obtained from a Connected App configured in Salesforce under: **Setup → App Manager → New Connected App **Drimify uses the OAuth 2.0 Client Credentials flow.
* **External ID Field Name: **The API name of the field used to match (upsert) records — typically something like&#32;`Email_External_Id__c`&#32;or a custom external ID field on the Contact or Lead object. This field must be marked as an **External ID** in Salesforce.
* **External ID Source**: A dropdown allowing you to select which Drimify data field should be used as the matching key (for example: Email).
* **Verify Connection:** Tests the Salesforce OAuth connection before saving.

## ⚠️ Required Salesforce Fields

Salesforce enforces required object-level fields. If you are upserting Leads, Salesforce requires at minimum:

* `lastName` — required for Lead creation

If you are upserting Contacts, Salesforce requires:

* `lastName` — required for Contact creation

Although Email is not required by Salesforce's default schema, it is almost always necessary as an External ID to properly match and deduplicate records during upserts. Without a reliable External ID match, Salesforce may create duplicate records or return an error.

### Best Practice
Always map at least:

* Last Name
* Email

when connecting to Salesforce. Omitting Last Name will cause the webhook to fail and the record will not be created or updated.

# Mapping Fields

Available for all three integration types, **Map Fields** lets you specify exactly which Drimify data fields are sent to your integration, and under which key names.
Click **+ Add Field** to add a mapping row.

Each row consists of:

* **Webhook field (left)** — the key name that will appear in the outgoing payload (defined by you to match your integration requirements)
* **→ Source field (dropdown on the right)** — the value source for this field. You can either:
  * Select a **Drimify data field** (e.g. App Reference, Email, Score) to send a dynamic value collected from the participant
  * Select **Static value** to send a fixed, hardcoded value every time the webhook fires — an additional text input will appear where you enter the value (e.g. `My_Value`). Useful for passing constants like an event name, a source identifier, or an environment tag.

## Available Drimify Source Fields

| Display Name | Field Key |
| ---- |
| Postal Address | `address` |
| App ID | `appId` |
| App Reference | `appReference` |
| Code | `code` |
| Company Name | `companyName` |
| Connection Country | `connectionCountry` |
| Country | `country` |
| Country Code | `countryCode` |
| Custom Checkbox | `customCheckbox` |
| Custom Format | `customFormat` |
| Custom Text Field | `customText` |
| Date | `date` |
| Date of Birth | `dob` |
| Date With Timezone | `dateWithTimezone` |
| Email | `email` |
| First Name | `firstName` |
| Gender | `gender` |
| ID | `id` |
| Idunic | `idunic` |
| IP Address | `ipAddress` |
| Last Name | `lastName` |
| Levels Played | `levelsPlayed` |
| Locale | `locale` |
| Newsletter Opt-In | `optinNewsletter` |
| Phone Number | `phoneNumber` |
| Played | `played` |
| Postal Code | `cp` |
| Profile | `profil` |
| Profile UID | `profilUid` |
| Prize Ref | `prizeRef` |
| Prize Title | `prizeTitle` |
| Prize UID | `prizeUid` |
| Referral | `referral` |
| Score | `score` |
| Select Value | `selectValue` |
| Select Value 2 | `selectValue2` |
| Session ID | `sessionId` |
| Time Taken | `timeTaken` |
| City | `town` |
| Updated At | `updatedAt` |
| Updated At Timestamp | `updatedAtTimeStamp` |
| Username | `username` |
| Website Address | `website` |

You can add as many mappings as needed.
To remove a mapping, click the trash icon on the right side of the row.

# Available in Workspaces

At the bottom of the integration form, the **Available in Workspaces** section lets you use the toggle next to each workspace to control which workspace can use the integration.
Click **Select All** to enable the integration for all workspaces at once.

# Save and Manage Integrations

Once all fields are completed, click **Save Changes** to create the integration. The integration will then appear in the main Integrations list. You can edit or delete existing integrations from this list at any time. Click **Cancel** to discard unsaved changes.

---

# Mailer Integrations

Mailer integrations allow you to send transactional emails (e.g. confirmations, results, or follow-ups) directly from your Drimify experiences using your preferred email provider.

### Add a Mailer Integration

1. Go to **Integrations → Mailer Integrations**
2. Click **Add Mailer Integration**
3. Select your provider:
* Amazon SES
* Brevo
* Drimify
* Mailgun
* Mailjet
* Mandrill
* SendGrid
* Tipimail
* Custom SMTP

### Configure your Mailer Integration

#### General Settings

All providers share the following general settings:

* **Integration Name** – Internal name to identify your integration
* **Sender Name** – Name displayed as the email sender
* **Sender Email** – Email address used to send emails (not applicable for Drimify — see below)
* **BCC Email** *(optional)* – Add an email address to receive a copy of all outgoing emails

#### Authentication

Each provider requires specific credentials. See the provider-specific setup section below for details.

#### Test Your Connection

After entering your credentials, click **Send Test Email** to verify your integration is working correctly. A "Test email sent successfully" confirmation will appear if the connection is valid.

||| ⚠️ The integration must pass the connection test before it can be used. If the test is skipped or fails, the mailer will not be available for use in your experiences.

#### Template Parameter Fields

Map Drimify data fields to your email provider's template variables. This section is available for providers that support dynamic email templates: **Brevo, Mailgun, Mailjet, Mandrill, SendGrid, and Tipimail**.

* **Parameter name** – The variable name expected in your email template
* **Field** – The corresponding Drimify data (e.g. First Name, Email, Score, etc.)

Click **Add Field** to create additional mappings.

| 💡 This allows you to personalise emails dynamically using player data collected in your experience.

#### Available in Workspaces
Select which workspaces can use this mailer integration.

### Provider-Specific Setup

#### Amazon SES

What you need:

* An AWS IAM user with `ses:SendEmail` permissions
* API Access Key and API Private Key (from AWS IAM)
* Your AWS region (e.g. `eu-west-1`, `us-east-1`)
* Session Token *(only if using temporary/STS credentials)*
* A verified sender email or domain in Amazon SES

Steps:

1. In AWS IAM, create a user with SES send permissions and generate an access key pair
2. In Drimify, enter your **API Access Key**, **API Private Key**, and **Region**
3. If using temporary credentials, also enter the **Session Token**
4. Ensure your sender email or domain is verified in Amazon SES
5. Click **Send Test Email** to validate the connection
6. Save your integration

#### Brevo

What you need:

* A Brevo API key

Steps:

1. In your Brevo account, generate an API key under **Settings → API Keys**
2. Paste it into the **API Key** field in Drimify
3. Click **Send Test Email** to validate the connection
4. Save your integration

#### Drimify

No authentication required. Emails are sent via Drimify's internal email infrastructure ([notification@digitaservice.com](mailto:notification@digitaservice.com)).
What you need:

* A sender name
* A reply-to email address (e.g. [contact@yourcompany.com](mailto:contact@yourcompany.com))
* Optionally, a BCC email address

Steps:

1. Select **Drimify** as your provider
2. Enter your **Sender Name** and **Reply-To Email**
3. Optionally add a **BCC Email**
4. Select the workspaces that should use this integration and save

| 💡 Use this option if you don't have a third-party email provider or want to get started quickly without any external configuration.

#### Mailgun

What you need:

* A Mailgun API key
* Your sending domain registered in Mailgun
* Your API region (US or EU)

Steps:

1. In your Mailgun account, retrieve your API key and sending domain
2. In Drimify, enter your **API Key**, **API Domain**, and **API Region**
3. Click **Send Test Email** to validate the connection
4. Save your integration

#### Mailjet

What you need:

* A Mailjet API Access Key and API Private Key

Steps:

1. In your Mailjet account, go to **Account Settings → REST API → API Key Management**
2. Copy your **API Access Key** and **API Private Key**
3. Enter both in Drimify
4. Click **Send Test Email** to validate the connection
5. Save your integration

#### Mandrill

What you need:

* A Mandrill API key *(Mandrill is a Mailchimp transactional email add-on)*

Steps:

1. In your Mandrill account, go to **Settings → API Keys** and generate a key
2. Paste the **API Key** into Drimify
3. Click **Send Test Email** to validate the connection
4. Save your integration

#### SendGrid

What you need:

* A SendGrid API key with Mail Send permissions

Steps:

1. In your SendGrid account, go to **Settings → API Keys** and create a key with **Mail Send** permissions
2. Paste the **API Key** into Drimify
3. Click **Send Test Email** to validate the connection
4. Save your integration

#### Tipimail

What you need:

* A Tipimail API User and API Key *(Tipimail is Sarbacane's transactional email service)*

Steps:

1. In your Tipimail account, go to **Settings → SMTP & APIs** and retrieve your **API User** and **API Key**
2. Enter both in Drimify
3. Click **Send Test Email** to validate the connection
4. Save your integration

| 💡 Tipimail supports dynamic email templates: reference your template by its name and use the Template Parameter Fields section to map Drimify data to your template's variables.

#### Custom SMTP

What you need:

* Your SMTP server hostname
* SMTP port (typically `587` for TLS, `465` for SSL)
* SMTP login (usually your email address)
* SMTP password

Steps:

1. Retrieve your SMTP credentials from your email hosting provider or server configuration
2. In Drimify, enter your **Host**, **Port**, **Login**, and **Password**
3. Click **Send Test Email** to validate the connection
4. Save your integration