Comment configurer des webhooks pour être notifié des nouvelles soumissions de formulaires PDF

Benjamin André-Micolon

Une manière puissante d'envoyer les soumissions à votre application ou de connecter SimplePDF avec d'autres services comme Zapier ou Activepieces est d'utiliser des webhooks.

Webhooks ?

Les webhooks permettent de connecter des applications entre elles en envoyant des données en temps réel d'une application à une ou plusieurs autres lorsqu'un événement spécifique se produit.

Dans SimplePDF, chaque fois qu'un PDF est soumis via votre portail d'entreprise, soit en utilisant des liens de formulaire ou en l'intégrant dans votre site web, un événement est envoyé contenant le nom du document, un lien vers le PDF rempli et un lien vers les données structurées du formulaire, entre autres.

Les données structurées du formulaire sont la partie qui intéresse le plus la majorité des intégrations : au lieu d'analyser le PDF rempli, vous recevez chaque réponse au format JSON, prête à être stockée, routée ou transmise à un autre système. Voir Extraire les données structurées du formulaire ci-dessous.

De là, les possibilités sont infinies et vous pouvez laisser libre cours à votre imagination.

Par exemple, vous pourriez enregistrer ces informations dans une feuille Google ou l'intégrer avec Zapier ou Activepieces pour déverrouiller encore plus de possibilités !

Configurer des webhooks dans SimplePDF

La configuration des webhooks est disponible avec le plan BASIC

• Connectez-vous à votre compte
• Accédez à la vue des paramètres du compte

• Cliquez sur Mettre à jour la configuration
• Entrez l'URL du webhook du service ou de l'application à laquelle vous souhaitez envoyer les événements

• Optionnel : spécifiez les en-têtes à envoyer avec le webhook

C'est fait ! Un événement sera envoyé chaque fois qu'il y aura une nouvelle soumission

Événements des webhooks

Vous trouverez ci-dessous les événements envoyés par SimplePDF au webhook que vous avez configuré.

type: "submission.created",
data: {
  document: {
    id: "b7615a68-9e1f-4eac-bd20-5e80632a4d9e",
    name: "your_document.pdf",
  },
  submission: {
    id: "80146d5b-a068-490f-8eb9-fe393ba11396",
    submitted_at: "2023-06-04T11:54:58.995Z",
    url: "short_lived_15min_url",
    field_data_url: "short_lived_15min_url",
  },
  context: {
    environment: "production",
    customer_id: "123"
  }
}

Extraire les données structurées du formulaire

field_data_url est un lien éphémère vers les données du formulaire de la soumission au format JSON, de sorte que vous n'avez jamais à analyser le PDF rempli pour lire les réponses.

Il capture chaque champ, qu'il s'agisse d'un champ intégré au PDF (un champ de formulaire natif, aussi appelé AcroField) ou d'un champ que votre destinataire a rempli et que vous avez ajouté par-dessus le document dans SimplePDF. Les deux apparaissent dans la même liste, chacun portant son id, son name et la value soumise :

{
  "fields": [
    { "id": "first_name__widget_1", "name": "First name", "value": "Jane" },
    { "id": "agreed_to_terms__widget_1", "name": "Agreed to terms", "value": "checked" },
    { "id": "f_a1b2c3", "name": "Reviewer note", "value": "A note added on top of the PDF" }
  ]
}

Chaque value est du texte brut (une signature ou une image est transmise sous forme d'image intégrée). Comme chaque entrée porte à la fois l'id et le name, vous pouvez associer chaque réponse à son champ et l'envoyer directement dans une feuille de calcul, une base de données ou un formulaire en aval tel qu'une réponse à un questionnaire FHIR. Ce même JSON peut être renvoyé à SimplePDF pour préremplir un autre document, de sorte qu'une soumission effectue un aller-retour sans accroc.

Les champs d'un document sont stables, et vous contrôlez la façon dont chacun est nommé : configurez vos champs une fois (renommez-les, marquez-les comme obligatoires, définissez des valeurs par défaut) et chaque soumission future arrivera avec le même id et le même name. Cela transforme l'association des données du webhook à votre propre système en une configuration unique qui fonctionne ensuite sans changement pour chaque soumission. (name vaut null pour un champ que vous avez ajouté par-dessus mais jamais nommé.)

field_data_url expire après 15 minutes, comme url. Si vous en avez besoin plus tard, récupérez-en un nouveau depuis l'API avec GET /documents/{document_id}/submissions/{submission_id}. Il vaut null pour les soumissions enregistrées avant que les données structurées du formulaire ne soient disponibles.

À propos du contexte

Lorsque vous intégrez SimplePDF dans votre site web, vous pouvez vouloir associer des informations supplémentaires aux soumissions.

Par exemple, vous pourriez vouloir :

• Savoir si la soumission a été initiée depuis un environnement de développement vs un production.
• Envoyer des détails supplémentaires sur qui a soumis le formulaire (comme un utilisateur connecté) pour faciliter le traitement de la soumission.

Apprenez comment spécifier un contexte dans la documentation de SimplePDF embed

Terrain de jeu

Nous aimons les exemples chez SimplePDF, alors pourquoi ne pas voir un exemple réel de ce à quoi ressemblent les webhooks ?

1. Modifiez le contexte ci-dessous (cliquez pour éditer le contenu)

{"environment":"production","customer_id":"123"}

2. Soumettez ce formulaire

3. Le webhook envoyé par SimplePDF apparaîtra ici

Si vous avez des questions, n'hésitez pas à contacter support@simplepdf.com