RefCampaignDocs
Integration

Webhooks

Recevez les événements de votre programme RefCampaign dans votre CRM ou vos automatisations.

RefCampaign envoie des requêtes HTTPS POST quand votre programme évolue. Les webhooks sont disponibles à partir du plan Growth.

Configurer un endpoint

Ouvrez Réglages → Webhooks → Ajouter un webhook, saisissez une URL HTTPS et choisissez les événements à recevoir. Un compte peut avoir jusqu’à cinq endpoints. Le secret de signature (whsec_…) n’est affiché qu’une fois.

Utilisez Envoyer un test pour vérifier votre récepteur. La rotation crée immédiatement un nouveau secret, tandis que l’ancien reste valide pendant 24 heures. Durant cette période, chaque livraison contient une signature v1 par secret valide, et le secret ne peut pas être renouvelé avant la fin de la période.

Événements

ÉvénementÉmis quand
affiliate.createdUn affilié est créé.
affiliate.approvedUn affilié est approuvé.
conversion.recordedUne conversion est enregistrée.
conversion.refundedUne conversion est remboursée.
commission.createdUne commission est créée.
commission.payableUne commission devient payable.
commission.paidUne commission est payée.
payout.initiatedUn paiement est créé.
payout.paidUn paiement aboutit.
payout.failedUn paiement fournisseur échoue.
fraud.flaggedUne activité suspecte est signalée.

Payload

{
  "id": "evt_01…",
  "object": "event",
  "apiVersion": "2026-05-01",
  "created": "2026-10-21T12:00:00.000Z",
  "type": "conversion.recorded",
  "data": {
    "object": {
      "id": "conv_abc",
      "amount": "49.9",
      "currency": "EUR"
    }
  }
}

L’identifiant id reste stable pendant les retries. Enregistrez-le avant de traiter l’événement et ignorez les doublons. data.object contient le snapshot sérialisé dans la même transaction que la modification métier ; les montants décimaux sont des chaînes. Un remboursement sur une commission payée émet aussi commission.created pour la commission négative de reprise. Pour fraud.flagged, data.object.object vaut commission (commission mise en revue par un signal de fraude), fraud_log (clic ou conversion suspects examinés) ou dispute (litige de paiement ouvert sur une conversion).

Les livraisons peuvent arriver dans le désordre, par exemple après un retry. Ordonnez les événements par created, ou relisez l’objet, plutôt que de vous fier à l’ordre d’arrivée.

Vérifier la signature

Chaque requête porte le header RefCampaign-Signature :

RefCampaign-Signature: t=<unix_seconds>,v1=<hex_sha256>[,v1=<hex_sha256>]

Chaque valeur v1 correspond à HMAC-SHA256(secret, "<t>.<rawBody>"). Vérifiez le corps brut avec une comparaison à temps constant et refusez les timestamps vieux de plus de cinq minutes.

Node.js

import express from 'express'
import { constructWebhookEvent, WEBHOOK_SIGNATURE_HEADER } from '@refcampaign/sdk/webhooks'

app.post('/refcampaign', express.raw({ type: 'application/json' }), (req, res) => {
  const event = constructWebhookEvent({
    secret: process.env.REFCAMPAIGN_WEBHOOK_SECRET!,
    payload: req.body,
    header: req.header(WEBHOOK_SIGNATURE_HEADER) ?? '',
  })
  queueOnce(event.id, event)
  res.sendStatus(204)
})

Python

import hashlib, hmac, time

def verify(secret: str, raw: bytes, header: str) -> bool:
    values = [part.strip().split('=', 1) for part in header.split(',') if '=' in part]
    timestamps = [value for key, value in values if key == 't']
    signatures = [value for key, value in values if key == 'v1']
    if not timestamps or not timestamps[0].isdigit():
        return False
    timestamp = int(timestamps[0])
    if abs(time.time() - timestamp) > 300:
        return False
    signed = str(timestamp).encode() + b'.' + raw
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, signature) for signature in signatures)

PHP

function verifyWebhook(string $secret, string $rawBody, string $header): bool {
    $timestamp = null;
    $signatures = [];
    foreach (explode(',', $header) as $part) {
        [$key, $value] = array_pad(explode('=', trim($part), 2), 2, null);
        if ($key === 't') $timestamp = (int) $value;
        if ($key === 'v1') $signatures[] = $value;
    }
    if (!$timestamp || abs(time() - $timestamp) > 300) return false;
    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
    foreach ($signatures as $signature) {
        if (hash_equals($expected, $signature)) return true;
    }
    return false;
}

Politique de livraison

  • Renvoyez un statut 2xx dans les 10 secondes après avoir accepté l’événement.
  • Les erreurs réseau, timeouts, réponses 408, 429 et 5xx sont relancés après 1 minute, 5 minutes, 30 minutes, 2 heures, 5 heures, 10 heures, 18 heures et 24 heures. Les autres 4xx sont définitifs.
  • RefCampaign exécute au maximum cinq livraisons en parallèle par endpoint et sérialise les tentatives d’une même livraison.
  • Après 20 tentatives consécutives en échec, RefCampaign met l’endpoint en pause et prévient le propriétaire du compte par e-mail. Un test réussi ou une relance manuelle réussie d’une livraison le réactive.
  • Le dashboard conserve les 50 dernières livraisons avec leurs tentatives, payloads et réponses. Une livraison en échec peut être relancée manuellement. Pendant les sept jours qui suivent une pause, ses événements sont enregistrés comme livraisons en échec : vous pouvez les relancer une fois l’endpoint rétabli. Désactiver vous-même un endpoint arrête cet enregistrement.

Migrer depuis l’ancien format

Les livraisons précédentes utilisaient X-RefCampaign-Signature et un corps plat avec event, data, timestamp et idempotencyKey. Pendant la période de migration, RefCampaign envoie encore ce header et les champs event, timestamp et idempotencyKey à la racine, en plus de l’enveloppe v1. Les noms d’événements changent : conversion.created devient conversion.recorded, conversion.commission_paid devient commission.paid, conversion.disputed devient fraud.flagged, et un litige perdu devient conversion.refunded. Les abonnements existants suivent le périmètre de l’événement v1 : fraud.flagged couvre aussi les commissions mises en revue et les revues anti-fraude de l’équipe, et conversion.refunded couvre tous les remboursements. L’objet se trouve désormais dans data.object. Passez à la dernière version de @refcampaign/sdk, puis lisez type, created, id et data.object.

Stockez les secrets dans un gestionnaire de secrets. Ne les placez jamais dans les logs ou le code client.

Sur cette page