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

```json
{
  "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` :

```text
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

```ts
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

```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

```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.
