DocTransform

Webhooks

Recevez un message signé dès qu’une exécution se termine, sans interroger l’API pour récupérer le fichier

Un webhook est une adresse à vous que DocTransform appelle chaque fois qu’une de vos exécutions se termine. Pensez à une sonnette : au lieu de demander sans cesse si l’exécution est finie, vous attendez, et DocTransform sonne quand elle l’est. Ce coup de sonnette est un court message appelé événement. Il indique quelle exécution est terminée et donne un lien vers le fichier.

Créer un webhook

Il vous faut une seule chose : une adresse qui commence par https:// et qui est joignable depuis internet. Un outil comme Zapier vous en donne une, votre propre serveur aussi.

  1. Ouvrez la carte Webhooks

    Allez sur votre page Compte et trouvez la carte Webhooks. Cliquez sur Ajouter un Webhook.

  2. Collez votre adresse

    Collez-la dans Adresse où envoyer les événements. Une exécution est terminée et Une exécution a échoué sont déjà cochés, ainsi que Pour tous les modèles. Ne les changez que si besoin.

  3. Enregistrez et envoyez un test

    Cliquez sur Enregistrer le Webhook, puis sur Envoyer un événement de test. La réponse s’affiche dans le Journal des livraisons du même écran : vous savez que cela marche avant une vraie exécution.

  4. Copiez le secret de signature

    Seulement si votre propre code vérifie les événements : sous Secret de signature, cliquez sur Afficher, puis sur Copier. Avec Zapier, Make ou n8n, vous pouvez passer cette étape.

Vous pouvez ajouter jusqu’à 5 webhooks, quel que soit le forfait. Les webhooks se gèrent uniquement dans la page Compte, pas par l’API. Les livraisons ne comptent jamais dans votre quota.

Remarque Interroger GET /runs/{id} fonctionne toujours et ne disparaîtra pas. Vous écrivez du code ? Lisez Vérifier les webhooks. Vous utilisez Zapier, Make ou n8n ? Il vous faut seulement l’adresse que ces outils vous donnent.

Ce qui arrive

Chaque événement est un POST avec un corps JSON en trois parties : type, timestamp (quand l’exécution s’est terminée) et data. Toutes les clés sont toujours présentes, et valent null quand elles ne s’appliquent pas, pour qu’un outil associe les mêmes champs à chaque fois. Jamais de contenu de fichier, de colonne, de nom de fichier ni de nom de modèle : pour les détails, interrogez GET /runs/{id}.

run.succeeded est envoyé quand le fichier est prêt :

{
  "type": "run.succeeded",
  "timestamp": "2026-09-27T10:15:00Z",
  "data": {
    "run_id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
    "template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
    "status": "succeeded",
    "download_url": "https://doctransform.xyz/api/v1/runs/run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58/download?expires=1790763300&signature=0000000000000000000000000000000000000000000000000000000000000000",
    "expires_at": "2026-09-30T10:15:00Z",
    "error": null
  }
}

run.failed est envoyé quand une exécution se termine sans fichier. Il n’a pas de lien, et error.code est l’un des codes d’erreur :

{
  "type": "run.failed",
  "timestamp": "2026-09-27T10:15:00Z",
  "data": {
    "run_id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
    "template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
    "status": "failed",
    "download_url": null,
    "expires_at": null,
    "error": {
      "code": "PIPELINE_FAILED",
      "message": "The pipeline failed while running the Template."
    }
  }
}

webhook.test est ce qu’envoie Envoyer un événement de test. Son lien ne fonctionne pas : ignorez-le avec if type == "webhook.test" :

{
  "type": "webhook.test",
  "timestamp": "2026-09-27T10:15:00+00:00",
  "data": {
    "run_id": "run_test",
    "template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
    "status": "succeeded",
    "download_url": "https://doctransform.xyz/api/v1/runs/run_test/download?expires=1790590500&signature=0000000000000000000000000000000000000000000000000000000000000000",
    "expires_at": "2026-09-28T10:15:00+00:00",
    "error": null
  }
}

Vérifier qu’un événement est authentique

Quiconque trouve votre adresse pourrait lui envoyer des données. Chaque événement porte une signature que seuls DocTransform et vous pouvez produire : votre code distingue ainsi un vrai événement d’un faux. Vérifier les webhooks explique comment, avec des exemples à copier.

Nouvelles tentatives et désactivation

Un événement n’est livré que lorsque votre adresse répond par un statut 2xx en moins de 10 secondes. Les redirections ne sont pas suivies. Tout le reste est retenté : une courte panne de votre côté ne fait rien perdre. Après chaque tentative échouée, DocTransform attend plus longtemps :

Après la tentative échouéeAttente avant la suivante
11 min
25 min
330 min
42 h
56 h
612 h
724 h
818 h

Cela fait 9 tentatives sur environ 2,6 jours (62 h 36 min, à plus ou moins 10 % près). Qu’un événement déjà traité revienne est normal : voir Bloquer les rejeux et les doublons.

Quand les livraisons échouent

Le webhook reste activé et indique qu’il échoue. Ouvrez son Journal des livraisons pour voir chaque tentative et la raison. Vous recevez un e-mail après 24 heures d’échecs. Dès que votre adresse répond de nouveau, la tentative suivante livre l’événement.

Le journal des livraisons donne à chaque tentative échouée l’un de ces motifs :

MotifEn clairQue faire
WEBHOOK_UNREACHABLENous n’avons pas pu joindre votre adresse : elle n’existe pas, est hors ligne ou nous a refusés.Vérifiez qu’il n’y a pas de faute dans l’adresse et que votre récepteur fonctionne.
WEBHOOK_TIMEOUTVotre adresse a mis plus de 10 secondes à répondre.Répondez d’abord et faites le travail lent ensuite.
WEBHOOK_REJECTEDVotre adresse a répondu, mais par une erreur au lieu d’un statut 2xx.Consultez le journal de votre récepteur pour voir pourquoi il a refusé.
WEBHOOK_REDIRECTEDVotre adresse nous a renvoyés vers une autre adresse, et nous ne suivons jamais cela.Collez plutôt l’adresse finale.
WEBHOOK_URL_BLOCKEDL’adresse pointe vers un réseau privé, nous avons donc cessé d’y envoyer.Utilisez une adresse https publique. Pour essayer sur votre propre ordinateur, voir Tester les webhooks en local.
WEBHOOK_SECRET_UNREADABLENous n’avons pas pu lire le secret de signature du webhook, donc rien n’a été envoyé.Ouvrez le webhook et cliquez sur Changer le secret.
WEBHOOK_DISABLEDLe webhook était désactivé, l’événement n’a donc pas été envoyé.Cliquez sur Activer.

Quand un webhook se désactive

Après 10 tentatives échouées d’affilée, étalées sur plus de 5 jours, le webhook passe à Désactivé et vous recevez un second e-mail. Plus rien n’est envoyé. Réparez votre adresse, puis cliquez sur Activer : il propose de renvoyer les livraisons arrêtées lors de la désactivation, des 3 derniers jours. Une exécution terminée pendant que le webhook était désactivé n’est pas envoyée : récupérez son fichier avec GET /runs/{id}/output, ou avec son lien de téléchargement tant qu’il dure. Vous pouvez aussi cliquer sur Renvoyer sur une livraison précise.

Quand votre adresse répond « disparue »

Si votre adresse répond 410 Gone, le webhook se désactive aussitôt, car cette réponse signifie qu’elle ne reviendra pas. Cela arrive souvent quand un Zap ou un scénario est supprimé ou laissé éteint. Remettez le récepteur en route, puis cliquez sur Activer.

Télécharger le fichier

download_url télécharge le fichier sans clé API jusqu’à expires_at. C’est 3 jours après la fin de l’exécution quand un webhook la reçoit, et 30 minutes sinon, ce qui vaut aussi pour GET /runs/{id}/output. Il vaut null pour run.failed, et pour une livraison envoyée après l’expiration du fichier, comme un Renvoyer tardif. Un lien expiré répond DOWNLOAD_LINK_EXPIRED : relancez le modèle.

Attention Quiconque a le lien peut télécharger le fichier jusqu’à son expiration. Ne le collez nulle part où d’autres le verraient.

Tester les webhooks en local

DocTransform envoie uniquement vers des adresses https publiques, donc localhost est refusé. Un tunnel donne à votre serveur local une adresse publique. Celui-ci ne demande pas de compte :

cloudflared tunnel --url http://localhost:8000

Collez l’adresse affichée, plus votre chemin, dans un webhook, puis cliquez sur Envoyer un événement de test. ngrok fait le même travail. Supprimez le webhook ensuite, car l’adresse du tunnel change à chaque fois.

Voir ce qui s’est passé

Activité de l’API, dans votre page Compte, liste chaque requête de vos clés API des 90 derniers jours, refus compris. Le Journal des livraisons de chaque webhook montre chaque tentative avec sa réponse et un bouton Renvoyer. Les deux sont reliés par l’identifiant de l’exécution : cliquez sur Voir cette exécution pour passer de l’un à l’autre.