Webhooks

Webhooks — Vue d'ensemble

Architecture event-driven, retry policy et structure des payloads.

Les webhooks Coffrify envoient des requêtes HTTP POST vers votre endpoint à chaque événement. C'est le mécanisme recommandé pour réagir aux transferts en temps réel - plus fiable que le polling.

Structure d'un payload

{
  "id":          "evt_01JXXXXXXXXXXXXXXXX",
  "type":        "transfer.completed",
  "created":     1716897600,
  "api_version": "2026-05-14",
  "data": {
    "object": {
      "id":          "tr_01JXXXXXXXXXXXXXXXX",
      "short_code":  "X9aB2c",
      "share_url":   "https://r.coffrify.com/X9aB2c",
      "status":      "completed",
      "file_count":  2,
      "total_size":  5242880,
      "expires_at":  "2026-06-02T10:00:00Z"
    }
  }
}

Politique de retry

Si votre endpoint retourne un statut non-2xx ou ne répond pas dans **10 secondes**, Coffrify réessaie avec un backoff exponentiel :

Immédiatement (tentative 1)
Après 5 minutes (tentative 2)
Après 30 minutes (tentative 3)
Après 2 heures (tentative 4)
Après 8 heures (tentative 5)

Endpoint doit répondre vite

Répondez **200 immédiatement** puis traitez l'event de façon asynchrone (file de traitement). Un traitement long qui expire déclenche un retry et risque de traiter l'event en double.

Idempotence

Chaque event a un `id` unique (`evt_...`). Stockez les IDs traités pour dédupliquer en cas de retry. Le même event peut être livré plusieurs fois.

Vérifier la signature

Chaque requête webhook inclut le header `Coffrify-Signature`. Vérifiez-le pour rejeter les requêtes non authentifiées. Voir [Signature & vérification HMAC](/docs-public/webhook-signatures).

Ordre de livraison

Ordre non garanti

Les events sont livrés au mieux en ordre chronologique, mais ce n'est pas garanti en cas de retry. Basez votre logique sur le timestamp `created` et l'état réel de l'objet, pas sur l'ordre de réception.