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.created | Un affilié est créé. |
affiliate.approved | Un affilié est approuvé. |
conversion.recorded | Une conversion est enregistrée. |
conversion.refunded | Une conversion est remboursée. |
commission.created | Une commission est créée. |
commission.payable | Une commission devient payable. |
commission.paid | Une commission est payée. |
payout.initiated | Un paiement est créé. |
payout.paid | Un paiement aboutit. |
payout.failed | Un paiement fournisseur échoue. |
fraud.flagged | Une 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
2xxdans les 10 secondes après avoir accepté l’événement. - Les erreurs réseau, timeouts, réponses
408,429et5xxsont relancés après 1 minute, 5 minutes, 30 minutes, 2 heures, 5 heures, 10 heures, 18 heures et 24 heures. Les autres4xxsont 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.