Feed the CRM from your product
Canopus keeps your contacts current through two endpoints. Your backend posts lifecycle events to a signed webhook; your site posts form submissions to a public lead endpoint. Both accept attribution, which is how Canopus later tells you which campaign a customer came from.
The CRM webhook
Endpoint: POST https://www.canopushq.io/api/webhooks/crm/{orgId}. The exact URL, with your organization id filled in, is on CRM, then Settings, then Webhook, together with the secret.
Generate the secret on that screen. It is shown once: store it in your product as CRM_WEBHOOK_SECRET. Regenerating it invalidates the old one immediately.
Sign every request: compute an HMAC-SHA256 of the raw request body with the secret, hex encoded, and send it in the X-Signature header. Both sha256=<hex> and the bare hex are accepted.
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,
})Send a ping event first: the settings screen shows "link verified" once one arrives, and ping needs no user object.
The event payload
{
"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 *
- Your unique id for the event, up to 120 characters. Canopus deduplicates on it, so a retry of the same event is safe.
- event_type *
- One of: 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
- ISO date of the event. Defaults to the time of receipt. Events older than the last one applied to a contact are ignored, except for last-seen.
- user.email *
- Required for every type except ping. Contacts are matched by external_id first, then by email; an unknown address creates a customer.
- user.external_id
- Your own user id, up to 120 characters. Send it: it keeps the match stable when an email changes.
- user.name / plan / status
- Free strings (120 / 60 / 60). The statuses Canopus reads are free, trialing, active (paying), past_due and churned: a free-plan user is free, never active. Some events set the status themselves: trial_started makes trialing, payment_failed makes past_due, churned makes churned.
- user.custom
- Up to 50 keys of strings (2000 max), numbers, booleans or null. They become traits on the contact; columns can be created automatically if you enable it. Send invited: true for a seat a customer gave a colleague: the Signs up, Starts paying and Leaves triggers leave that person out, since paying and leaving belong to the account that pays. The other triggers still apply. A trial_started_at date (set by user.trial_started) is the moment the Starts a trial trigger fires, and where a stalled trial starts counting.
- attribution
- Optional: utm_source, utm_medium, utm_campaign, utm_term, utm_content (120 each), referrer (500), landed_at (date), cnp (120). See the attribution section below.
| Response | Meaning |
|---|---|
| 200 {"status":"accepted"} | Applied. The body carries contact_id, created, and any refused custom keys with a reason. |
| 200 {"status":"duplicate"} | This event_id was already processed for your organization. Nothing changed. |
| 200 {"status":"pong"} | Your ping arrived and the signature is valid. |
| 200 {"status":"ignored"} | The event was emitted before this person was erased, and arrived after. Nothing was written. Do not retry. |
| 202 {"status":"failed"} | Stored but not applied; you can replay it from the events log in the app. |
| 401 | No signature or one that does not match the body. The response includes the byte count and SHA-256 of the body received, to debug serialization. |
| 413 / 422 / 429 | Body over 64 KiB; invalid JSON or schema (with per-field errors); rate limited (500 per minute, retry-after header). |
Deleting a user (GDPR)
When a user deletes their account, or asks you to erase their data, send user.deleted. Canopus finds the contact by external_id, then by email for older records that never had an id, and erases it for good: the contact, its timeline of events, its notes and fields, its campaign and sequence enrolments (so no sequence keeps running), the stored events about it, and the address and subject of the product mail sent to it.
The answer is always 200 {"status":"accepted"}, even when nobody matched, so resending the event is safe. If the erasure itself fails, the answer is a 5xx: retry it like any other.
Canopus keeps one register entry with no personal data in it: the event_id, the dates, and a salted hash of the email and of the external_id. It is what lets you show a regulator that the erasure happened. It also stops a late event from your queue (an update emitted before the deletion and retried after it) from bringing the person back: such an event answers ignored. A user.created dated after the deletion is a new sign-up and goes through.
Emails already sent stay counted in your monthly quota, without the person attached. A hard bounce or a complaint stays on the suppression list, because it protects your sending domain.
{
"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" }
}Un programme ambassadeur
Si votre produit gère un programme ambassadeur (affiliation), il reste la source de vérité : il décide qui est ambassadeur, calcule les commissions et les verse. Canopus enregistre qui a apporté qui et envoie l'email que vous avez écrit pour chaque événement du programme, depuis votre domaine, par votre flux transactionnel.
Sur le client apporté par un ambassadeur, ajoutez à user.custom referred_by (l'external_id de l'ambassadeur, la clé de jointure), referred_by_code, referred_via (link ou promo_code) et referred_at, sur user.created ou sur un user.updated ultérieur. La fiche de l'ambassadeur liste alors chaque client apporté, avec son plan et son statut, et toute vue peut filtrer sur referred_by.
{
"event_id": "evt_created_usr_456",
"event_type": "user.created",
"occurred_at": "2026-11-19T10:05:00.000Z",
"user": {
"external_id": "usr_456",
"email": "new.customer@example.com",
"custom": {
"referred_by": "usr_123",
"referred_by_code": "JEAN",
"referred_via": "link",
"referred_at": "2026-11-19T10:05:00.000Z"
}
}
}Sur l'ambassadeur, envoyez affiliate.created, affiliate.promo_code_created, affiliate.referral_signed_up, affiliate.commission_earned, affiliate.payout_requested et affiliate.payout_paid, dans la même enveloppe avec la même signature. Ils ne changent jamais le plan ni le statut et ne font jamais entrer ni sortir la personne d'une séquence, même quand l'ambassadeur est aussi client.
user.custom porte l'état de l'ambassadeur et n'accepte que des clés commençant par affiliate_. Les faits d'un événement (un montant, un lien, l'email masqué d'un filleul) vont dans data, affiché dans la chronologie et proposé comme variables à l'email, jamais écrit sur la fiche. Les emails s'écrivent dans CRM, puis Réglages, puis E-mails d'événements ; une adresse d'équipe peut recevoir les demandes de paiement.
N'envoyez jamais d'identifiant d'accès. Une clé comme set_password_url ou api_token est retirée avant tout stockage et nommée dans la liste refused de la réponse.
{
"event_id": "evt_payout_paid_po_8812",
"event_type": "affiliate.payout_paid",
"occurred_at": "2026-11-19T10:00:00.000Z",
"user": {
"external_id": "usr_123",
"email": "ambassador@example.com",
"custom": { "affiliate_paid_eur": 174, "affiliate_pending_eur": 0 }
},
"data": {
"amount_eur": 87,
"paid_at": "2026-11-19T10:00:00.000Z",
"affiliate_dashboard_url": "https://app.example.com/ambassador"
}
}An ambassador programme
If your product runs an ambassador (affiliate) programme, it stays the source of truth: it decides who is an ambassador, computes the commissions and pays them. Canopus records who brought whom and sends the email you wrote for each programme event, from your domain, through your transactional stream.
On the customer an ambassador brought, add referred_by (the ambassador's external_id, the join key), referred_by_code, referred_via (link or promo_code) and referred_at to user.custom, on user.created or on a later user.updated. The ambassador's record then lists every customer they brought, with plan and status, and any view can filter on referred_by.
{
"event_id": "evt_created_usr_456",
"event_type": "user.created",
"occurred_at": "2026-11-19T10:05:00.000Z",
"user": {
"external_id": "usr_456",
"email": "new.customer@example.com",
"custom": {
"referred_by": "usr_123",
"referred_by_code": "JEAN",
"referred_via": "link",
"referred_at": "2026-11-19T10:05:00.000Z"
}
}
}On the ambassador, send affiliate.created, affiliate.promo_code_created, affiliate.referral_signed_up, affiliate.commission_earned, affiliate.payout_requested and affiliate.payout_paid, in the same envelope with the same signature. They never change the plan or the status and never move the person into or out of a sequence, even when the ambassador is also a customer.
user.custom is the ambassador's state and only takes keys starting with affiliate_. The facts of one event (an amount, a link, the masked email of a referral) go in data, which is shown on the timeline and offered as variables to the email, never written to the record. Write the emails on CRM, then Settings, then Event emails; a team address can receive the payout requests.
Never send a credential. A key such as set_password_url or api_token is dropped before anything is stored and named in the refused list of the answer.
{
"event_id": "evt_payout_paid_po_8812",
"event_type": "affiliate.payout_paid",
"occurred_at": "2026-11-19T10:00:00.000Z",
"user": {
"external_id": "usr_123",
"email": "ambassador@example.com",
"custom": { "affiliate_paid_eur": 174, "affiliate_pending_eur": 0 }
},
"data": {
"amount_eur": 87,
"paid_at": "2026-11-19T10:00:00.000Z",
"affiliate_dashboard_url": "https://app.example.com/ambassador"
}
}Lead capture
Endpoint: POST https://www.canopushq.io/api/leads/{orgId}/{formKey}. Generate the form key on CRM, then Settings, then Lead capture; the screen shows the full URL. The key is not a secret: it is made to be in your page source, and CORS is open.
The endpoint accepts JSON, urlencoded and multipart, so a plain HTML form works with no JavaScript at all:
<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 *
- The only required field. A new address becomes a prospect on the first pipeline stage.
- name / company / source
- Free strings, 120 each. source is stored as the lead source label.
- utm / utm_*
- source, medium, campaign, term, content, 120 each. In a form, utm_source and friends map automatically.
- referrer / cnp
- Where the visitor came from (500) and the Canopus reference from the URL (120). Pass them when you have them.
- custom[key]
- Up to 30 keys, values string (500), number, boolean or null. Form fields named custom[key] map automatically; keys are lowercase, digits and underscores.
- website
- The honeypot. Keep it in the form, hidden: bots fill it, the submission answers 200 and nothing is written.
- Existing contacts are completed, never overwritten: a blank field is filled, a filled one is kept, and a customer is never demoted to prospect.
- Limits: 16 KiB body, 30 requests per minute per IP and per organization (429 with retry-after beyond).
- A bad or mismatched form key answers 404; validation failures answer 422 with per-field errors.
Attribution: the cnp parameter
Every link Canopus publishes for you carries utm_* parameters and one extra parameter, cnp, which names the exact campaign, post or sequence. There is no JavaScript snippet, no cookie and no visitor id: attribution works only if your pages pass these values back.
Capture cnp, the utm values and the referrer when a visitor lands, keep them through your signup (a hidden field, your session, wherever you keep such things), then send them in the lead call or in the attribution object of the webhook, ideally on user.created.
First touch wins, within a 14 day window from landed_at. On user.created, landed_at defaults to occurred_at; on the lead endpoint it defaults to the time the form is received. The result is stored on the contact and powers the Attribution screen: revenue by source, down to the campaign.