Webhooks

Une demande de document ne renvoie jamais le document terminé en ligne. Doclift le livre plus tard sous forme de webhook, une fois que chaque génération de la demande est terminée.

Configuration

Il n'existe aucun endpoint d'API pour enregistrer, lister, ou faire tourner une URL de webhook. La cible de livraison est un unique champ, Webhook URL, défini sur l'application externe depuis le dashboard Doclift (la même clé que celle que vous envoyez comme X-Api-Key).

Une requête est refusée d'emblée si l'application externe appelante n'a aucune URL de webhook configurée :

{
  "error": "Please add a webhook URL to this external application to use asynchronous generation. You can add one from your Doclift.io account."
}

Voir Génération asynchrone.

Quand il se déclenche

Une fois que chaque entrée document_generations de la demande est terminée (chacune soit success, soit error), Doclift envoie exactement un webhook pour toute la demande. Il n'y a ni webhook par génération, ni événement « démarré » séparé.

Payload

POST https://yourapp.com/webhooks/doclift
Content-Type: application/json
Accept: application/json
X-Doclift-Signature: sha256=<hex hmac>

{
  "id": 100004,
  "tag": "Batch#12",
  "type": "asynchrone",
  "timestamp": "2024-01-15T10:35:00+01:00",
  "documents_generations": [
    {
      "id": 100230,
      "tag": "Subscription#102",
      "generated_at": "2024-01-15T10:35:02+01:00",
      "created_at": "2024-01-15T10:35:00+01:00",
      "generation_status": "success",
      "file": {
        "filename": "Contract-1615737313.pdf",
        "url": "https://doclift.s3.eu-west-1.amazonaws.com/d207f8fe.pdf?[...]",
        "size": 40290
      }
    }
  ]
}

Les entrées documents_generations portent les mêmes champs que ceux décrits dans L'objet demande de document. L'url du fichier est un lien signé ne nécessitant aucune authentification pour être récupéré, valable 2 heures ; passé ce délai, récupérez à nouveau le document via Consulter une demande de document, dont les propres URLs de fichier restent valables 20 heures.

Vérification de la signature

Chaque requête de webhook porte X-Doclift-Signature: sha256=<hex hmac> : un HMAC-SHA256 du corps brut de la requête, avec pour clé le secret_key de votre application externe. C'est la même valeur que vous envoyez comme X-Api-Key ; il n'y a pas de secret de signature séparé.

computed = "sha256=" + OpenSSL::HMAC.hexdigest(
  "SHA256",
  api_secret_key,
  request.raw_post,
)

valid = ActiveSupport::SecurityUtils.secure_compare(
  computed,
  request.headers["X-Doclift-Signature"].to_s,
)

Calculez le HMAC sur le corps brut, pas sur une copie re-sérialisée du JSON analysé. Des différences d'espacement ou d'ordre des clés produiraient une signature différente.

Ce que votre endpoint doit répondre

Répondez avec un statut HTTP 2xx dans les 3 secondes. Tout autre code de statut, ou aucune réponse dans ce délai, compte comme une tentative de livraison échouée et alimente la politique de nouvelles tentatives ci-dessous.

Politique de nouvelles tentatives

Deux mécanismes indépendants peuvent relancer des tentatives autour d'une même demande de document, et chacun répond à une question différente. Les confondre vous fera mal interpréter l'un ou l'autre.

Les nouvelles tentatives de livraison du webhook s'appliquent une fois que la génération est déjà terminée et que Doclift essaie de vous remettre le résultat. Une réponse non-2xx, ou un échec de timeout/transport, planifie une nouvelle tentative de livraison avec un backoff exponentiel :

30s, 60s, 120s, 240s, ... plafonné à 30 minutes. webhooks_replays_count (voir Informations utilisateur) est le nombre de nouvelles tentatives en plus du premier essai. Une valeur par défaut de 3 signifie jusqu'à 4 tentatives de livraison au total avant que Doclift abandonne. Une valeur de 0 ou moins désactive entièrement les nouvelles tentatives.

Les nouvelles tentatives de génération du PDF ont lieu plus tôt et indépendamment, avant qu'il n'y ait quoi que ce soit à livrer. Cela n'a rien à voir avec votre endpoint de webhook ni avec webhooks_replays_count. Un document qui se rend avec succès déclenche tout de même exactement une livraison de webhook ordinaire une fois terminé.

Visibilité des échecs

Le champ status de la demande de document reflète le résultat de la génération (success une fois toutes les générations réussies, error sinon). Il ne dit rien sur le fait que le webhook ait ou non été livré avec succès à votre endpoint. Il n'y a aucun champ ni endpoint dans cette API qui rapporte le résultat de la livraison du webhook. Si votre endpoint ne renvoie jamais de 2xx et que les nouvelles tentatives sont épuisées, le document sous-jacent existe toujours et peut être récupéré avec Consulter une demande de document.