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

# Setting up the Givex extension

> What to supply, which settings to configure in CX Manager, and how the two Givex webhooks are connected.

Omneo installs the Givex extension for your tenant. Your part is to supply the Givex account details, choose the settings below, and connect Givex to the webhook URL Omneo provides.

## Before you start

Have these ready:

| Item                                              | Where it comes from                                                                                                                                        |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Givex DataConnect username and password           | Givex                                                                                                                                                      |
| Givex DataConnect host for your environment       | Givex. Development and production use different hosts. Give the host on its own, without a port.                                                           |
| Issuer name and email                             | Your brand. They appear on the eCert as the sender.                                                                                                        |
| A shared webhook secret for balance events        | Agreed with Givex, then applied by Omneo. You do not set it yourself. Givex signs each event with it, and events that are not signed with it are rejected. |
| A Credit Definition for imported cards (optional) | Created in CX Manager. Only needed if cards Omneo has not seen should become Credits.                                                                      |
| The Benefit Definitions that should issue eCerts  | Created in CX Manager. See [eCert issuance](/extensions/givex/ecert-issuance).                                                                             |

Omneo reaches your Givex host on Givex's standard service ports and retries across them if one is unavailable, so give the host without a port and make sure Givex has those ports open for your environment.

## Settings

Configure the extension in CX Manager under **Settings > Plugins > Givex**:

| Setting                     | Description                                                                                                                                                                                                                                                                                                                                    |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`                   | Turns the extension on or off for your tenant. Both flows stop while this is `false`.                                                                                                                                                                                                                                                          |
| `issuer_name`               | Sender name shown on the eCert. It also forms part of the Givex order reference.                                                                                                                                                                                                                                                               |
| `issuer_email`              | Address that receives the Givex order confirmation and appears as the greeting sender.                                                                                                                                                                                                                                                         |
| `givex_username`            | Your Givex DataConnect username.                                                                                                                                                                                                                                                                                                               |
| `givex_password`            | Your Givex DataConnect password.                                                                                                                                                                                                                                                                                                               |
| `connection_host`           | Your Givex DataConnect host, without a port. The default is the Givex development host, so change it before going live.                                                                                                                                                                                                                        |
| `credit_definition_handle`  | Handle of the Credit Definition used when a `BALANCE` event arrives for a card Omneo has never seen and no Credit Definition name matches the card face name on the event. Leave blank, with no name match available, to keep creation off.                                                                                                    |
| `create_profile_if_missing` | When a `BALANCE` event carries an email address that matches no Omneo Profile, `true` creates the Profile and assigns the Credit to it, and `false` leaves the Credit unassigned. Defaults to `false`.                                                                                                                                         |
| `event_field_mapping`       | Names the Givex event fields that carry the recipient email, the card face name and the Profile first and last name. Givex has not confirmed these names, so set them here if your Givex account sends different ones. Each entry falls back to its default when it is missing or invalid. See [Balance sync](/extensions/givex/balance-sync). |

<Note>
  Settings changes are not picked up instantly. Tell your Omneo contact when you change a setting so they can apply it.
</Note>

<Info>
  If your tenant ran the Givex extension before balance sync was available, Omneo has to reinstall the extension on your tenant before Credits will sync. Ask your Omneo contact to confirm this has been done before you ask Givex to start sending `BALANCE` events.
</Info>

## Connecting the webhooks

<Steps>
  <Step title="Omneo registers the Benefit webhook">
    Omneo registers a `benefit.created` webhook on your tenant that points at the extension. This is what starts eCert issuance. No action is needed from you.
  </Step>

  <Step title="Give Givex the balance webhook URL">
    Omneo provides a webhook URL for your tenant. Ask Givex to send `BALANCE` events to that URL, signed with the shared secret you agreed. Events that are not signed correctly are rejected.
  </Step>

  <Step title="Tag the Benefit Definitions">
    Add the tag `issue-ecert` to each Benefit Definition that should produce an eCert, and give it a `value` and a `period`. See [eCert issuance](/extensions/givex/ecert-issuance).
  </Step>

  <Step title="Enable the extension">
    Set `enabled` to `true`. Issue a test Benefit to a Profile with a real email address and confirm the eCert arrives and the Benefit gains its redeem codes.
  </Step>
</Steps>

## Related

* [Givex overview](/extensions/givex/overview)
* [Credits](/concepts/commerce/credits)
* [Benefits](/concepts/incentives/benefits)