Cycle de vie & webhooks

ShopiMind pilote votre intégration en lui envoyant des webhooks de cycle de vie. Le kit les reçoit, vérifie leur signature et les dispatche — vous n'écrivez aucun code de réception ni de sécurité. Vous réagissez, si besoin, via des hooks.

Deux flux entrants, à ne pas confondre

Cette page couvre les webhooks émis par ShopiMind vers votre intégration (cycle de vie). Les appels entrants émis par votre propre application vers votre intégration (pour pousser une donnée en temps réel) sont décrits dans Middleware entrant — ils utilisent une signature différente, par-installation.

Le cycle de vie

Install  →  (Configurer)  →  Activate  →  … config_updated …  →  Deactivate  →  Uninstall

Événement	Quand	Effet
integration.installed	Le marchand installe votre intégration.	ShopiMind crée l'installation et vous transmet la clé API (access_token), révoquée pour l'instant.
integration.activated	Le marchand active, après configuration.	ShopiMind dé-révoque la clé, envoie la config ; le kit teste la connexion, provisionne, puis lance la synchro initiale.
integration.config_updated	La configuration change.	Le kit rejoue le provisioning (best-effort).
integration.deactivated	Le marchand désactive.	ShopiMind re-révoque la clé.
integration.uninstalled	Le marchand désinstalle.	ShopiMind supprime la configuration et révoque la clé.

La clé API n'est valide que pendant le statut « actif »

Tout appel à l'API ShopiMind avant activate ou après deactivate renvoie 401. Le kit gère cette clé pour vous (chiffrée dans son store) ; vos appels via ctx.spm ne fonctionnent qu'en statut actif.

La signature

Chaque webhook entrant (cycle de vie, test de connexion, données distantes) est signé par ShopiMind et vérifié par le kit :

• en-têtes X-Shopimind-Signature (HMAC-SHA256 hexadécimal) et X-Shopimind-Timestamp (secondes) ;
• signature = HMAC-SHA256("${timestamp}.${corps_brut}", webhook_secret) ;
• vérifiée sur les octets bruts du corps, en temps constant, avec une fenêtre anti-rejeu (300 s par défaut).

Le webhook_secret est celui que ShopiMind vous a communiqué à l'enregistrement, placé dans WEBHOOK_SECRET. C'est tout : le kit rejette automatiquement une requête mal signée, trop ancienne ou sans en-têtes. Vous n'avez aucun code de validation à écrire.

installation_id — un jeton opaque

Les webhooks portent un installation_id : un jeton opaque émis par ShopiMind, stable dans le temps (y compris après désinstallation/réinstallation). Le kit l'expose sous ctx.installationId. Ne l'interprétez jamais : ce n'est pas un identifiant de boutique, c'est l'identité de l'installation côté ShopiMind.

Réagir au cycle de vie — les hooks

Pour exécuter votre propre logique à certains moments, déclarez des hooks dans defineIntegration. Tous reçoivent le ctx et sont facultatifs :

hooks: {
  onActivate:      async (ctx) => { /* après activation validée */ },
  onConfigUpdated: async (ctx) => { /* après changement de config */ },
  onDeactivate:    async (ctx) => { /* à la désactivation */ },
  onUninstall:     async (ctx) => { /* à la désinstallation */ },
}

Pas de hook onInstall

Le kit n'exécute de hook qu'à partir de l'activation. Il n'y a pas de onInstall : à l'installation, la clé API est encore révoquée et aucun appel n'est possible. Faites votre initialisation dans onActivate.

Un usage fréquent dans onActivate : enregistrer le pont de corrélation entre l'installation ShopiMind et votre compte interne, et transmettre à votre application le secret des routes entrantes —

onActivate: async (ctx) => {
  ctx.setExternalAccount({ id: ctx.settings.account, name: ctx.settings.account });
  // ctx.inboundSecret peut être communiqué à votre app pour qu'elle signe ses appels entrants
  // → voir « Middleware entrant »
}

Le contrat de réponse

Le kit répond toujours à ShopiMind avec HTTP 200 et { "success": true } quand tout va bien (et un échec contrôlé sinon). Vous n'avez pas à gérer ce contrat — il est porté par le runtime.

Pour aller plus loin

• Le kit d'intégration — routes exposées, ctx.
• Middleware entrant — les appels entrants émis par votre application.
• Manifeste & enregistrement — obtenir le webhook_secret.
• Configuration — test_connection et données distantes.