Manifest & registration

For an integration to be installable, ShopiMind must know about it: its slug, its configuration, its widgets, its webhooks. You provide this information as a manifest (a neutral JSON generated from your code), which the ShopiMind team registers. Registration is manual and reviewed (a guarantee of marketplace quality).

1. Generate the manifest

The kit provides buildIntegrationManifest(integration). Add a small script to your integration:

// src/print-manifest.ts
import { buildIntegrationManifest } from '@shopimind/integration-kit-js';
import { myIntegration } from './integration.js';

console.log(JSON.stringify(buildIntegrationManifest(myIntegration), null, 2));

// package.json
{
  "scripts": {
    "print:manifest": "node dist/print-manifest.js"
  }
}

Then:

yarn build
yarn print:manifest > integration.manifest.json

2. What the manifest contains

Field	Contents
manifest_version	1.
slug, name, version	Integration identity.
categories?	Categories (neutral slugs, e.g. ['pos']).
icon_url?, short_description?, description?, documentation_url?	Display metadata.
config_schema	Your configuration form.
widgets	Your widgets.
webhooks	Relative paths: /webhook/receive, /webhook/test-connection, /webhook/remote-data/{resource}.
lifecycle_events	['install','activate','deactivate','uninstall','config_updated'].
remote_resources	The resources of your dynamic select fields (e.g. ['stores']).

A deliberately neutral artifact

The manifest contains no secret, no SQL, no partner identifier, no status, no absolute URL. It describes your integration; it does not touch ShopiMind's internal control plane. You can version it and share it safely.

3. Send it to ShopiMind

Send your integration.manifest.json to dev@shopimind.com along with:

• the public URL of your integration (the host where your webhooks run, e.g. https://my-app.example.com);
• the partner (your organization) to attach it to.

4. What ShopiMind does

The technical team:

1. validates the manifest;
2. resolves the categories (your slugs → internal identifiers);
3. generates a webhook_secret (the HMAC secret that will sign the webhooks sent to your integration);
4. composes the absolute URLs of your webhooks from your public host (e.g. https://my-app.example.com/webhook/receive);
5. chooses the status (usually inactive at first, while the review takes place), then registers the integration.

5. Retrieve the webhook_secret

ShopiMind shares the generated webhook_secret with you. Set it in your integration's WEBHOOK_SECRET environment variable: this is the secret the kit uses to verify the signature of every incoming webhook (see Lifecycle & webhooks).

# integration .env
WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep the secret server-side

The webhook_secret is a shared secret. It must never appear in a public repository, a log, or on the client side.

Updating an integration

When your integration evolves (a new config field, a new widget, a new version): regenerate the manifest (yarn print:manifest) and send it back to dev@shopimind.com. The slug identifies your integration; the registration is updated. Your webhook_secret stays unchanged.

Going further

• Lifecycle & webhooks: how the webhook_secret is used.
• Configuration & Widgets: what feeds the manifest.
• Complete example (Hiboutik): from code to manifest.