Quelles données PDFMonkey envoie-t-il dans un webhook ?

PDFMonkey envoie un objet DocumentCard encapsulé dans une clé "document". Il contient l’identifiant du document, son statut, l’URL de téléchargement, le nom de fichier, les métadonnées (meta), le type de sortie, l’identifiant du modèle, etc. Le payload d’origine n’est pas inclus : utilisez le champ meta pour transmettre les données dont vous avez besoin.

Comment vérifier qu’un webhook provient bien de PDFMonkey ?

PDFMonkey utilise Svix pour envoyer les webhooks. Chaque webhook est signé avec une clé unique par endpoint. Vous pouvez vérifier la signature avec les bibliothèques officielles Svix pour Node.js, Python, Ruby, Go et d’autres langages.

Peut-on recevoir des webhooks uniquement pour certains modèles ?

Oui. Lors de la création d’un endpoint webhook, ajoutez un channel au format template-VOTRE_ID_DE_MODELE pour filtrer les notifications. Vous pouvez aussi utiliser folder-VOTRE_ID_DE_DOSSIER pour recevoir les webhooks de tous les modèles d’un dossier.

PDFMonkey envoie-t-il des webhooks pour les documents en échec ?

Oui. PDFMonkey déclenche deux types d’événements : documents.generation.success lorsqu’un document est généré avec succès, et documents.generation.failure en cas d’échec. Abonnez-vous aux deux pour gérer les erreurs dans votre intégration.

Webhooks : notifications de génération de documents en temps réel

Les webhooks vous permettent de recevoir une notification HTTP dès qu’un document est généré, pour réagir immédiatement sans interroger l’API en boucle. PDFMonkey utilise Svix pour envoyer les webhooks avec des tentatives automatiques et la vérification des signatures.

Cette page couvre les types d’événements, le format du payload, la configuration du routage (par workspace, par modèle ou par channel personnalisé) et la vérification des signatures.

Types d’événements

PDFMonkey déclenche deux types d’événements webhook :

Événement	Quand il se déclenche
`documents.generation.success`	Un document a été généré avec succès. Le champ `download_url` est disponible.
`documents.generation.failure`	La génération d’un document a échoué. Le champ `failure_cause` décrit l’erreur.

Abonnez-vous à l’un ou aux deux selon vos besoins. La plupart des intégrations s’abonnent au minimum à documents.generation.success.

Payload du webhook

Chaque webhook envoie un objet DocumentCard encapsulé dans une clé document :

{
  "document": {
    "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
    "app_id": "d6b4e8f2-7a3c-4d1e-9f5b-2c8a1d3e6f90",
    "created_at": "2050-03-13T12:34:56.181+02:00",
    "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
    "document_template_identifier": "My Invoice Template",
    "download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/...",
    "failure_cause": null,
    "filename": "2050-03-14 Peter Parker.pdf",
    "meta": {
      "_filename": "2050-03-14 Peter Parker.pdf",
      "clientRef": "spidey-616"
    },
    "output_type": "pdf",
    "preview_url": "https://preview.pdfmonkey.io/...",
    "public_share_link": null,
    "status": "success",
    "updated_at": "2050-03-13T12:34:59.412+02:00"
  }
}

DocumentCard, pas Document

Le payload du webhook est un DocumentCard, pas un Document complet. Il ne contient pas les champs payload (données dynamiques), generation_logs ni checksum. Si vous devez transmettre des données à votre gestionnaire de webhooks, utilisez le champ meta lors de la création du document. Consultez l’objet DocumentCard pour la référence complète des attributs.

Définir un webhook pour tout le workspace

Pour recevoir des notifications pour chaque document généré dans un workspace :

Cliquez sur le lien Webhooks dans la navigation principale.
Cliquez sur le bouton + Add Endpoint.
Saisissez l’URL de votre endpoint.
Sélectionnez le(s) type(s) d’événement souhaité(s) (documents.generation.success, documents.generation.failure ou les deux).

Votre endpoint est désormais appelé chaque fois qu’un document du workspace est généré.

Définir un webhook spécifique à un modèle

Dans de nombreux cas (notamment avec les plateformes no-code comme Zapier, Make ou n8n), vous aurez besoin d’un webhook qui ne se déclenche que pour un modèle précis.

Copiez l’identifiant du modèle que vous souhaitez cibler.
Cliquez sur le lien Webhooks dans la navigation principale.
Cliquez sur le bouton + Add Endpoint.
Saisissez l’URL de votre endpoint et sélectionnez le(s) type(s) d’événement.
Dans le champ channels, ajoutez template-VOTRE_ID_DE_MODELE.

template-07C63E0B-620F-44A9-AF9F-4CA0DA025A0A

Votre endpoint est désormais appelé uniquement lorsqu’un document est généré à partir de ce modèle.

Les channels sont sensibles à la casse

Lorsque vous ajoutez un identifiant de modèle ou de dossier dans la liste des channels, collez-le toujours en majuscules. Un identifiant en minuscules ne sera pas reconnu et votre endpoint ne sera jamais appelé.

Cibler plusieurs modèles ou un dossier

Si vous avez besoin du même endpoint webhook pour plusieurs modèles (mais pas tous), vous pouvez ajouter jusqu’à 3 channels à un seul endpoint.

Si 3 channels ne suffisent pas, regroupez les modèles dans un dossier et utilisez l’identifiant du dossier comme channel. Ainsi, tout modèle de ce dossier déclenchera le webhook.

Suivez les mêmes étapes que ci-dessus, mais ajoutez folder-VOTRE_ID_DE_DOSSIER dans la liste des channels :

folder-440DA20B-C5A0-A0A9-C62F-4070FAF963EA

Channels personnalisés via meta

Vous pouvez router les webhooks dynamiquement pour chaque document en définissant la clé _webhook_channel dans le champ meta du document. Cela ajoute un channel supplémentaire à la notification webhook de ce document.

{
  "document": {
    "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
    "payload": "{}",
    "status": "pending",
    "meta": "{\"_webhook_channel\": \"order-42\"}"
  }
}

Configurez ensuite un endpoint webhook avec order-42 comme channel. Seuls les documents incluant cette valeur dans leur meta déclencheront cet endpoint.

Combinaison avec les channels de modèle

La notification webhook d’un document inclut toujours le channel de son modèle (et celui du dossier, le cas échéant) en plus de tout channel personnalisé défini dans meta. Un même événement webhook peut donc correspondre à plusieurs endpoints.

Vérifier les signatures des webhooks

Les webhooks étant des requêtes HTTP envoyées à une URL publique, un attaquant pourrait usurper l’identité de PDFMonkey en envoyant une fausse requête à votre endpoint. Pour éviter cela, Svix signe chaque webhook avec une clé secrète unique par endpoint.

Vous devez vérifier la signature de chaque webhook entrant avant de le traiter. Svix propose des bibliothèques pour les langages courants qui gèrent la vérification en quelques lignes de code.

Découvrez comment vérifier les signatures dans la documentation de vérification de Svix.

Vérifiez toujours en production

Ignorer la vérification des signatures expose votre endpoint à des requêtes falsifiées. Vérifiez toujours la signature du webhook avant d’agir sur les données reçues.

Questions fréquentes

Les webhooks fonctionnent-ils avec la génération d’images ?

Oui. Les webhooks se déclenchent pour tous les formats de sortie (PDF, PNG, JPG, WebP). Les types d’événements sont identiques quel que soit le format.

Le download_url du payload est-il permanent ?

Non. Le download_url est un lien signé temporaire valable 1 heure. Téléchargez le fichier dès réception du webhook, ou récupérez une URL fraîche ultérieurement via l’API. Consultez l’URL de téléchargement pour plus de détails.

Le webhook contient-il les données dynamiques (payload) d’origine ?

Non. Le webhook envoie un DocumentCard qui ne contient pas le champ payload. Stockez les données nécessaires dans le champ meta lors de la création du document ; meta est inclus dans le webhook.

Que se passe-t-il si mon endpoint est indisponible ?

Svix retente automatiquement les envois échoués avec un backoff exponentiel sur plusieurs heures. Vous pouvez surveiller les tentatives et rejouer manuellement les messages échoués depuis la section Webhooks du tableau de bord PDFMonkey.

Comment tester les webhooks en développement ?

Utilisez un service de tunnel comme ngrok ou localtunnel pour exposer votre serveur local sur Internet. Pointez votre endpoint webhook vers l’URL du tunnel, puis générez un document de test depuis le tableau de bord.

Puis-je utiliser l’endpoint synchrone à la place des webhooks ?

Oui. L’endpoint /api/v1/documents/sync attend la fin de la génération et retourne le résultat en une seule requête. C’est pratique pour le prototypage mais limité à 6 minutes. Pour la production, les webhooks sont plus fiables et scalables. Voir Génération synchrone.

Pages associées

Statuts et cycle de vie des documents : comprendre quand les webhooks se déclenchent dans le cycle de vie d’un document
L’URL de téléchargement : fonctionnement des liens temporaires et comment les rafraîchir
Référence API Documents : documentation complète des endpoints et des champs
L’objet DocumentCard : référence complète des attributs du payload webhook
Nom de fichier personnalisé : utiliser le champ meta pour définir des noms de fichiers et transmettre des données aux webhooks
Générer des documents via l’API : workflow complet de génération asynchrone
Générer des documents via une intégration : utiliser les webhooks avec Zapier, Make ou n8n

Questions fréquentes

Quelles données PDFMonkey envoie-t-il dans un webhook ?: PDFMonkey envoie un objet DocumentCard encapsulé dans une clé "document". Il contient l’identifiant du document, son statut, l’URL de téléchargement, le nom de fichier, les métadonnées (meta), le type de sortie, l’identifiant du modèle, etc. Le payload d’origine n’est pas inclus : utilisez le champ meta pour transmettre les données dont vous avez besoin.
Comment vérifier qu’un webhook provient bien de PDFMonkey ?: PDFMonkey utilise Svix pour envoyer les webhooks. Chaque webhook est signé avec une clé unique par endpoint. Vous pouvez vérifier la signature avec les bibliothèques officielles Svix pour Node.js, Python, Ruby, Go et d’autres langages.
Peut-on recevoir des webhooks uniquement pour certains modèles ?: Oui. Lors de la création d’un endpoint webhook, ajoutez un channel au format template-VOTRE_ID_DE_MODELE pour filtrer les notifications. Vous pouvez aussi utiliser folder-VOTRE_ID_DE_DOSSIER pour recevoir les webhooks de tous les modèles d’un dossier.
PDFMonkey envoie-t-il des webhooks pour les documents en échec ?: Oui. PDFMonkey déclenche deux types d’événements : documents.generation.success lorsqu’un document est généré avec succès, et documents.generation.failure en cas d’échec. Abonnez-vous aux deux pour gérer les erreurs dans votre intégration.
Que se passe-t-il si mon endpoint webhook est indisponible ?: Svix retente automatiquement les envois échoués avec un backoff exponentiel sur plusieurs heures. Vous pouvez surveiller les tentatives et rejouer manuellement les messages échoués depuis la section Webhooks du tableau de bord PDFMonkey.