Webhooks

Un webhook est une adresse de votre serveur que Fofo Express appelle à chaque événement de vos livraisons, y compris celles créées depuis l’application. Votre site met la commande à jour sans interroger l’API en boucle.

Configurer une adresseCopier le lien

Le propriétaire de la boutique ajoute l’adresse (HTTPS obligatoire) et choisit les événements. Un secret de signature whsec_… est affiché une seule fois ; il peut être régénéré. Un bouton « Tester » envoie un événement ping.

ÉvénementsCopier le lien

Chaque événement est envoyé une seule fois par adresse et par livraison.

ContenuCopier le lien

POST /votre-adresse HTTP/1.1
Content-Type: application/json
Fofo-Event: delivery.delivered
Fofo-Event-Id: 6f1c2a54-…
Fofo-Signature: t=1791812548,v1=5f2b…

{
  "id": "6f1c2a54-…",
  "type": "delivery.delivered",
  "createdAt": "2026-10-12T14:02:11.000Z",
  "data": {
    "id": "…",
    "reference": "FX-522PDJ",
    "externalRef": "WC-10482",
    "status": "DELIVERED",
    "…": "…"
  }
}

data est la livraison telle que la renvoie GET /deliveries/{id} au moment de l’événement. Pour l’état le plus récent, relisez la livraison : l’ordre d’arrivée des événements n’est pas garanti.

Vérifier la signatureCopier le lien

Fofo-Signature contient l’horodatage t (secondes) et v1, le HMAC-SHA256 en hexadécimal de "{t}.{corps brut}" calculé avec votre secret. Refusez la requête si la signature ne correspond pas ou si t date de plus de 5 minutes.

function fofo_signature_valide(string $secret, string $entete, string $corps): bool {
    parse_str(str_replace(',', '&', $entete), $parts);
    $t = (int) ($parts['t'] ?? 0);
    if (!isset($parts['v1']) || abs(time() - $t) > 300) {
        return false;
    }
    $attendu = hash_hmac('sha256', $t . '.' . $corps, $secret);
    return hash_equals($attendu, $parts['v1']);
}

$corps = file_get_contents('php://input');
if (!fofo_signature_valide(getenv('FOFO_WEBHOOK_SECRET'), $_SERVER['HTTP_FOFO_SIGNATURE'] ?? '', $corps)) {
    http_response_code(400);
    exit;
}
$evenement = json_decode($corps, true);
http_response_code(200);

Réponse et nouvelles tentativesCopier le lien

• Répondez par un code 2xx en moins de 10 secondes ; faites les traitements longs ensuite.
• Sinon, Fofo Express réessaie après 1, 5, 15, 60, 180, 360 puis 720 minutes.
• Une adresse en échec continu pendant 72 heures est désactivée et le propriétaire prévenu par email. La réactiver remet le compteur à zéro.
• Le journal des envois (30 jours) montre chaque tentative, avec un bouton « Renvoyer ».
• Utilisez Fofo-Event-Id pour ignorer un événement déjà traité.