Aller au contenu

Alimenter le CRM depuis votre produit

Canopus garde vos contacts à jour par deux endpoints. Votre backend poste les événements de cycle de vie sur un webhook signé ; votre site poste les formulaires sur un endpoint public de leads. Les deux acceptent l'attribution, ce qui permet ensuite à Canopus de vous dire de quelle campagne vient un client.

Le webhook CRM

Endpoint : POST https://www.canopushq.io/api/webhooks/crm/{orgId}. L'URL exacte, avec votre id d'organisation, est sur CRM, puis Réglages, puis Webhook, avec le secret.

Générez le secret sur cet écran. Il est affiché une seule fois : stockez-le dans votre produit sous CRM_WEBHOOK_SECRET. Le régénérer invalide l'ancien immédiatement.

Signez chaque requête : calculez un HMAC-SHA256 du corps brut de la requête avec le secret, encodé en hexadécimal, et envoyez-le dans l'en-tête X-Signature. sha256=<hex> et l'hex nu sont tous deux acceptés.

import { createHmac } from 'node:crypto'

const body = JSON.stringify(payload)
const signature = createHmac('sha256', process.env.CRM_WEBHOOK_SECRET)
  .update(body)
  .digest('hex')

await fetch('https://www.canopushq.io/api/webhooks/crm/' + orgId, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Signature': 'sha256=' + signature,
  },
  body,
})

Envoyez d'abord un événement ping : l'écran de réglages affiche « lien vérifié » dès qu'un ping arrive, et ping n'exige pas d'objet user.

Le payload d'événement

{
  "event_id": "evt_01J9ABCDEF",
  "event_type": "user.created",
  "occurred_at": "2026-10-04T09:30:00Z",
  "user": {
    "email": "ada@customer.example",
    "external_id": "usr_42",
    "name": "Ada",
    "plan": "pro",
    "custom": { "seats": 3 }
  },
  "attribution": {
    "utm_source": "newsletter",
    "referrer": "https://news.example/issue-12",
    "landed_at": "2026-10-01T18:04:00Z",
    "cnp": "c:0192f3a1-7c2e-7b1a-9f44-3d2a8c1b6e90"
  }
}
event_id *
Votre id unique pour l'événement, 120 caractères maximum. Canopus déduplique dessus : rejouer le même événement est sans risque.
event_type *
Un parmi : ping, user.created, user.updated, user.trial_started, user.plan_changed, user.payment_failed, user.payment_recovered, user.churned, user.reactivated, user.activity, user.deleted.
occurred_at
Date ISO de l'événement. Par défaut : l'heure de réception. Les événements plus anciens que le dernier appliqué au contact sont ignorés, sauf pour la dernière activité.
user.email *
Requis pour tous les types sauf ping. Le contact est rapproché par external_id d’abord, puis par email ; une adresse inconnue crée un client.
user.external_id
Votre propre id d'utilisateur, 120 caractères maximum. Envoyez-le : il garde le rapprochement stable quand un email change.
user.name / plan / status
Chaînes libres (120 / 60 / 60). Les statuts que Canopus lit sont free, trialing, active (payant), past_due et churned : un utilisateur du plan gratuit est free, jamais active. Certains événements fixent le statut eux-mêmes : trial_started donne trialing, payment_failed donne past_due, churned donne churned.
user.custom
Jusqu'à 50 clés : chaînes (2000 max), nombres, booléens ou null. Elles deviennent des traits du contact ; les colonnes peuvent se créer automatiquement si vous l'activez. Envoyez invited: true pour un siège qu'un client a donné à un collègue : les déclencheurs S'inscrit, Passe au payant et Part écartent cette personne, puisque payer et partir appartiennent au compte qui paie. Les autres déclencheurs s'appliquent. La date trial_started_at (posée par user.trial_started) est le moment où part le déclencheur Démarre un essai, et le point de départ du silence d'un essai.
attribution
Optionnel : utm_source, utm_medium, utm_campaign, utm_term, utm_content (120 chacun), referrer (500), landed_at (date), cnp (120). Voir la section attribution plus bas.
RéponseSignification
200 {"status":"accepted"}Appliqué. Le corps porte contact_id, created, et les clés custom refusées avec leur raison.
200 {"status":"duplicate"}Cet event_id a déjà été traité pour votre organisation. Rien n’a changé.
200 {"status":"pong"}Votre ping est arrivé et la signature est valide.
200 {"status":"ignored"}L'événement a été émis avant l'effacement de cette personne et il est arrivé après. Rien n'a été écrit. Ne réessayez pas.
202 {"status":"failed"}Stocké mais pas appliqué ; vous pouvez le rejouer depuis le journal des événements dans l'app.
401Pas de signature, ou une signature qui ne correspond pas au corps. La réponse inclut la taille en octets et le SHA-256 du corps reçu, pour déboguer la sérialisation.
413 / 422 / 429Corps au-delà de 64 Kio ; JSON ou schéma invalide (avec les erreurs par champ) ; limite de débit (500 par minute, en-tête retry-after).

Supprimer un utilisateur (RGPD)

Quand un utilisateur supprime son compte, ou vous demande d'effacer ses données, envoyez user.deleted. Canopus retrouve le contact par external_id, puis par email pour les anciennes fiches qui n'ont jamais eu d'identifiant, et l'efface pour de bon : la fiche, sa chronologie d'événements, ses notes et ses champs, ses inscriptions aux campagnes et aux séquences (aucune séquence ne continue), les événements stockés qui la concernent, et l'adresse et l'objet des emails produit qui lui ont été envoyés.

La réponse est toujours 200 {"status":"accepted"}, même si personne ne correspond : renvoyer l'événement est donc sans risque. Si l'effacement lui-même échoue, la réponse est un 5xx : réessayez comme pour tout autre événement.

Canopus garde une seule entrée de registre, sans aucune donnée personnelle : l'event_id, les dates, et une empreinte salée de l'email et de l'external_id. C'est ce qui vous permet de prouver l'effacement à la CNIL. Elle empêche aussi un événement en retard dans votre file (une mise à jour émise avant la suppression et réessayée après) de faire revenir la personne : un tel événement répond ignored. Un user.created daté d'après la suppression est une nouvelle inscription et passe.

Les emails déjà envoyés restent comptés dans votre quota mensuel, sans la personne. Un rebond définitif ou une plainte reste sur la liste de suppression, parce qu'il protège votre domaine d'envoi.

{
  "event_id": "evt_01J9DELETE01",
  "event_type": "user.deleted",
  "occurred_at": "2026-11-08T14:00:00.000Z",
  "user": { "external_id": "usr_42", "email": "ada@customer.example" }
}

Capture de leads

Endpoint : POST https://www.canopushq.io/api/leads/{orgId}/{formKey}. Générez la clé de formulaire sur CRM, puis Réglages, puis Capture de leads ; l'écran affiche l'URL complète. La clé n'est pas un secret : elle est faite pour vivre dans le source de votre page, et le CORS est ouvert.

Le endpoint accepte JSON, urlencoded et multipart : un formulaire HTML nu fonctionne, sans aucun JavaScript :

<form action="https://www.canopushq.io/api/leads/{orgId}/{formKey}" method="post">
  <input type="email" name="email" required />
  <input type="text" name="name" />
  <!-- honeypot: keep it, bots fill it and are quietly dropped -->
  <input type="text" name="website" tabindex="-1" autocomplete="off" hidden />
  <button type="submit">Subscribe</button>
</form>
await fetch('https://www.canopushq.io/api/leads/{orgId}/{formKey}', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'ada@visitor.example',
    source: 'landing-footer',
    utm: { source: 'newsletter', medium: 'email' },
    cnp: new URLSearchParams(location.search).get('cnp') ?? undefined,
    referrer: document.referrer || undefined,
  }),
})
email *
Le seul champ requis. Une adresse nouvelle devient un prospect sur la première étape du pipeline.
name / company / source
Chaînes libres, 120 chacune. source est stocké comme libellé de provenance du lead.
utm / utm_*
source, medium, campaign, term, content, 120 chacun. Dans un formulaire, utm_source et les autres sont reconnus automatiquement.
referrer / cnp
D'où venait le visiteur (500) et la référence Canopus de l'URL (120). Passez-les quand vous les avez.
custom[key]
Jusqu'à 30 clés : chaîne (500), nombre, booléen ou null. Les champs nommés custom[key] sont reconnus ; les clés sont en minuscules, chiffres et underscores.
website
Le honeypot. Gardez-le dans le formulaire, caché : les bots le remplissent, la soumission répond 200 et rien n’est écrit.
  • Les contacts existants sont complétés, jamais écrasés : un champ vide est rempli, un champ rempli est conservé, et un client n'est jamais rétrogradé en prospect.
  • Limites : corps de 16 Kio, 30 requêtes par minute par IP et par organisation (429 avec retry-after au-delà).
  • Une clé de formulaire fausse ou dépareillée répond 404 ; une validation qui échoue répond 422 avec les erreurs par champ.

Attribution : le paramètre cnp

Chaque lien que Canopus publie pour vous porte des paramètres utm_* et un paramètre de plus, cnp, qui nomme la campagne, le post ou la séquence exacte. Il n'y a pas de snippet JavaScript, pas de cookie et pas d'id de visiteur : l'attribution ne fonctionne que si vos pages renvoient ces valeurs.

Capturez cnp, les valeurs utm et le referrer quand un visiteur atterrit, gardez-les jusqu'à son inscription (un champ caché, votre session, où vous gardez ce genre de choses), puis envoyez-les dans l'appel de lead ou dans l'objet attribution du webhook, idéalement sur user.created.

Le premier contact gagne, dans une fenêtre de 14 jours depuis landed_at. Sur user.created, landed_at vaut occurred_at par défaut ; sur le endpoint de leads, l'heure de réception du formulaire. Le résultat est stocké sur le contact et alimente l'écran Attribution : le revenu par source, jusqu'à la campagne.