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.