Drupal

ai12z Drupal Module Installation and Setup Guide

The ai12zhooks module connects your Drupal site to ai12z. It has two parts:

1. Web controls — the module auto-injects the ai12z web-component library from the CDN (cdn.ai12z.net/pkg/ai12z@<version>) onto your node pages, so AI-powered search, chatbot, and copilot widgets render on your site. The library version is configurable (leave blank or latest for the newest release).
2. Content sync — Drupal's entity create / update / delete hooks POST each change to your ai12z connector webhook in real time (published content only — drafts are never synced). A Run Initial Sync button bulk-syncs existing content, and a Check Config button verifies the setup.

Compatibility

Module	Drupal core	Drush
ai12zhooks	Drupal 10 & 11 (^10 || ^11)	Drush 12 / 13

Get your connector details from ai12z

Before configuring Drupal, open the connector in the ai12z portal and gather a few values. In the portal, go to your project → Connector Store → open the Drupal connector to reach the Connector Configuration screen.

note

The Drupal connector is push-based: your Drupal site sends content to ai12z in real time (and in bulk via Run Initial Sync). ai12z does not crawl or pull from your site, so no crawler or RestAPI pull credentials are required — the API Key below is the connector key ai12z uses to authenticate those pushes.

1. Connector Id and Agent Id — shown at the top of the page, each with a copy button.
2. Drupal Site URL — enter your Drupal site's base URL. This is your own site, e.g. https://your-drupal-site.com/ (or http://localhost:8280/ for a local test site).
3. API Key — click Manage Keys, then Generate a key and copy it. (Two keys are available so you can rotate them.) This is the key you will paste into Drupal.

Keep the API Key, Connector Id, and Agent Id handy — you enter them in the Drupal webhook form in Step 4.

Requirements

• Drupal 10 or 11.
• The module depends on the following modules, which are enabled automatically when you install ai12zhooks:
  • serialization (core)
  • rest (core)
  • basic_auth (core)
  • restui (contributed)

restui is a contributed module, so it must be present on the server before you enable ai12zhooks. On Drupal 10 and 11, install it with Composer rather than a version-specific archive:

composer require 'drupal/restui:^1.22'

Step 1: Downloading the Module

Download the latest module.

• ai12zhooks.zip

Step 2: Installing the Module

Drupal 11

Drupal 11 removed the ability to install modules from a URL or uploaded archive through the admin UI. The old Update Manager installer was deprecated in Drupal 10.3 and removed in 11.0 — on Drupal 11 the module is renamed Update Status and only reports available updates. Install ai12zhooks by placing its files on the server, as below. The browser "Add from a URL" flow only works on Drupal 10.2 and earlier.

2.1 Add the Module Files

• Extract ai12zhooks.zip into your site's modules directory — for example web/modules/custom/ai12zhooks (create modules/custom if it does not exist). If you manage the module in your own repository, add it via Composer instead.

2.2 Enable the Module

• Log in to your Drupal admin and go to Extend (admin/modules).
• Filter for ai12z and check "ai12z hook (ai12zhooks)".
• Click Install. When prompted, confirm enabling the dependent modules (serialization, rest, restui, basic_auth).

Alternatively, enable it from the command line:

drush en ai12zhooks -y

Step 3: Opening the ai12z Configuration

The ai12z configuration lives in the administration menu under Configuration → Web services → ai12z (/admin/config/services/ai12hook).

• Open Configuration → Web services → ai12z.
• Click Add hook to create a new webhook configuration.

Step 4: Configuring the Webhook

Fill out the webhook form and save.

4.1 Enter the configuration values

Field	Required	Description
Label	Yes	A recognizable name for this webhook (e.g. ai12z sync).
API Key	Yes*	Your ai12z API Key. Copy it from the ai12z portal and paste it here (see below). It is sent as the x-api-key header on every request to ai12z. The field is masked while you type (Show / Hide toggle) and the saved key is never redisplayed — leave the field blank on later edits to keep it. *Best practice (recommended for production): set the key per environment in settings.php instead — see Setting the ai12z endpoint and API key per environment. When settings.php sets the key, that key is used for every request and this field becomes read-only with the note "The API key is set in settings.php for this environment."
Connector Id	Yes	Provided by ai12z — found in the ai12z portal.
Agent Id	Yes	Provided by ai12z — found in the ai12z portal.
Web Control Version	No	The ai12z web-controls library version to inject. Leave blank or set latest for the newest release, or pin a specific version (e.g. 1.2.3).
Content Types	No	The content types (node types) to sync. Run Initial Sync processes only the selected types, and the selection is reported to ai12z when you run Check Config.
Exclude Fields	No	Field machine names (comma or newline separated) to leave out of the content payload — excluded from both the raw fields data and the aggregated ai12z_content text. Drupal system fields (revision, translation, uuid, …) are always excluded.
Hook URL	No	Only shown in local/dev builds. Leave blank to post to the configured ai12z endpoint (see Setting the ai12z endpoint and API key per environment); a value here overrides the endpoint for this webhook only.
Enabled Events	Yes	The content events to send to ai12z. Tick Create, Update, and Delete for the content you want kept in sync. At least one event is required.
Only sync publicly visible content	—	Checked by default. Unpublished and draft content is never synced, regardless of this setting — only published nodes trigger the webhook. When checked, published content an anonymous visitor cannot view (member-only) is also skipped. Uncheck to sync member-only content into a private assistant; every synced item carries an ai12z_isPrivate flag (false when the content is publicly visible) that ai12z uses to set the document's visibility.
Active	Yes	Leave checked so the webhook is live.

Copying your API Key from ai12z: In the ai12z portal, open your project's connector settings and copy the API Key. Back in Drupal, on the Add hook form (Configuration → Web services → ai12z → Add hook), paste it into the API Key field. The field is masked while you type; click Show to verify what you entered, then Hide it again before saving. Once saved, the key is never redisplayed — leave the field blank on later edits to keep it.

For production sites, the recommended setup is to skip this field entirely and set the key per environment in settings.php — see Setting the ai12z endpoint and API key per environment.

note

Label, API Key (unless set in settings.php), and at least one Enabled Event are required. If you save without selecting an event, Drupal returns "Outgoing webhooks require one or more events to operate."

4.2 Save the configuration

• Ensure all values are correct and click Save.

Step 5: Verifying and Syncing Content

After saving (or while editing the webhook), two actions are available:

• Check Config — validates your Connector Id and Agent Id against ai12z, authenticated with your API Key. Use this to confirm the configuration is correct. (This button and Run Initial Sync enable once Connector Id and Agent Id are filled in; the API Key comes from the settings.php override when one is set, otherwise from the field or the saved key.)
• Run Initial Sync — bulk-sends your existing content to ai12z. Run this once after the initial setup.

From then on, content stays in sync automatically: publishing, updating, and deleting content each POST to ai12z in real time.

Setting the ai12z endpoint and API key per environment

By default the module posts content to the production ai12z endpoint (https://integrate.ai12z.net/api/connector/). To point a site at a different environment — for local testing or UAT — override the endpoint in settings.php. This uses Drupal's configuration override system, so no rebuild or per-webhook change is needed:

// Local development
$config['ai12zhooks.settings']['ai12z_api'] = 'http://localhost:5005/api/connector/';

// UAT
$config['ai12zhooks.settings']['ai12z_api'] = 'https://integrate-dev.ai12z.net/api/connector/';

// Best practice: set the API key here too (leave the webhook form's API Key
// field empty). The key stays out of exported configuration and the site
// database, and each environment gets its own key.
$config['ai12zhooks.settings']['ai12z_api_key'] = 'your-api-key';

Setting ai12z_api_key in settings.php is the recommended production setup: the key never enters exported configuration (drush config:export) or the database, and deployments across local / UAT / production each carry their own key. When it is set, the override is authoritative — it is used for every webhook (real-time sync, Check Config, and Run Initial Sync), it takes precedence over any key saved on the webhook form, and the form's API Key field becomes read-only with a note that the key is set in settings.php.

Leave the webhook's Hook URL field blank to use this configured endpoint. A value entered in Hook URL overrides the endpoint for that single webhook only.

note

Local testing with Docker: if Drupal runs inside a container, localhost points at the container, not your host machine. To reach a service running on your host, use host.docker.internal (e.g. http://host.docker.internal:5005/api/connector/) or a public tunnel URL. This applies to local testing only — UAT and production use the ai12z hostnames above.

Web Controls

Once the module is enabled and a webhook is configured, the ai12z web-component library is injected automatically on node pages, pulling from https://cdn.ai12z.net/pkg/ai12z@<version>/…. The <version> is taken from the Web Control Version field (falling back to latest when it is blank). To pin or upgrade the widgets, change Web Control Version on the webhook configuration.

(Optional) Drush Commands

The module ships two Drush commands for automation and debugging:

# List all configured webhooks
drush ai12zhooks:list

# Trigger all active webhooks for a given event
drush ai12zhooks:trigger entity:node:create