Postback serveur à serveur

Suivez les conversions en appelant l'API REST directement depuis votre backend, sans le SDK.

Le SDK est le chemin recommandé pour les stacks JavaScript et TypeScript. Si vous êtes sur un autre runtime — PHP, Python, Ruby, Go, Elixir — ou si vous ne voulez pas de dépendance, appelez les endpoints REST publics directement. Ce guide couvre le pattern le plus utilisé : un postback serveur à serveur déclenché depuis votre backend de checkout après un paiement réussi.

Quand utiliser le postback

Le postback est le bon pattern quand :

La conversion a lieu côté serveur (webhook Stripe, IPN PayPal, processeur de paiement custom).
Vous avez besoin de garanties de livraison plus strictes que ce qu'un pixel navigateur peut offrir.
Vous opérez sur une stack non-JS.
La session navigateur peut être perdue entre le clic et la conversion (Safari ITP, cross-device, app mobile).

Si la conversion est liée à une page que le client est en train de visiter, le SDK est plus simple.

Endpoint

POST /api/v1/conversions/track
Authorization: Bearer <VOTRE_CLE_API>
Content-Type: application/json

Payload

{
  "sessionId": "string (optionnel)",
  "customerEmailHash": "string, SHA-256 hex (optionnel)",
  "amount": 49.9,
  "currency": "EUR",
  "metadata": { "orderId": "ord_42" },
  "isSynthetic": false
}

Champ	Type	Requis	Notes
`sessionId`	string	un des deux	Identifiant de session de tracking depuis le cookie de clic. Préféré quand intact.
`customerEmailHash`	string	un des deux	SHA-256 hex de l'email client lowercased. Fallback.
`amount`	number	oui	Valeur de la conversion dans la devise ci-dessous. Doit être positif.
`currency`	string	oui	Code ISO 4217 à 3 lettres.
`metadata`	object	non	Format libre. Persisté sur la conversion, exposé dans les exports.
`isSynthetic`	boolean	non	Marque la ligne comme un test (exclue de la facturation et des rapports).

Soit sessionId soit customerEmailHash doit être présent. Si les deux sont passés, sessionId gagne.

Calculer le hash de l'email

Hashez côté serveur, pas côté client

Le hash est un identifiant de fallback ; si vous le calculez dans le navigateur, un attaquant peut le rejouer pour s'attribuer des conversions. Hashez toujours côté serveur, après avoir vérifié que l'email appartient bien au client qui paie.

import hashlib
email = customer_email.lower().strip()
email_hash = hashlib.sha256(email.encode()).hexdigest()

$emailHash = hash('sha256', strtolower(trim($email)));

require 'digest'
email_hash = Digest::SHA256.hexdigest(email.downcase.strip)

Le hash est ce que nous stockons. L'email en clair ne quitte jamais votre infrastructure.

Exemple : handler webhook Stripe

Pattern typique : votre serveur reçoit déjà un webhook Stripe checkout.session.completed. Étendez le handler pour déclencher un postback RefCampaign.

# Python / Flask
import os
import requests
import hashlib

REFCAMPAIGN_KEY = os.environ['REFCAMPAIGN_API_KEY']
REFCAMPAIGN_URL = 'https://app.refcampaign.com/api/v1/conversions/track'

def on_stripe_completed(session):
    email_hash = hashlib.sha256(
        session.customer_details.email.lower().encode()
    ).hexdigest()

    requests.post(
        REFCAMPAIGN_URL,
        headers={
            'Authorization': f'Bearer {REFCAMPAIGN_KEY}',
            'Content-Type': 'application/json',
        },
        json={
            'customerEmailHash': email_hash,
            'amount': session.amount_total / 100,
            'currency': session.currency.upper(),
            'metadata': {'stripeSessionId': session.id},
        },
        timeout=10,
    )

Idempotence et retries

L'endpoint est idempotent sur sessionId — deux appels avec le même sessionId pour le même marchand dans une fenêtre de cinq minutes renvoient la même conversion (le second est un no-op). Avec customerEmailHash seulement, une déduplication soft matche le clic le plus récent dans la fenêtre d'attribution de la campagne.

Si votre handler webhook retry sur erreur transitoire, c'est sûr — les déclenchements dupliqués ne créent pas de conversions dupliquées.

Pour les retries au niveau réseau : respectez le header Retry-After sur 429, traitez les 5xx comme transitoires avec backoff, traitez les 4xx comme terminaux (pas de retry, log + alerte).

Vérifier la livraison

Le tableau de bord marchand affiche les conversions entrantes en temps réel. Pour les pipelines automatisés, requêtez la liste des conversions pour confirmer l'arrivée :

curl https://app.refcampaign.com/api/v1/conversions?campaignId=cmp_xxx&limit=10 \
  -H "Authorization: Bearer $REFCAMPAIGN_API_KEY"

Sécurité

Envoyez la clé API uniquement sur HTTPS.
Stockez-la dans un gestionnaire de secrets — jamais dans le code source.
Utilisez une clé dédiée par environnement (production / staging / local).
Voir authentification pour la checklist complète.

Postback serveur à serveur

Sur cette page