Come configurare i webhook per ricevere notifiche sulle nuove compilazioni dei moduli PDF

Benjamin André-Micolon

Un modo potente per inviare le compilazioni alla tua applicazione o collegare SimplePDF con altri servizi come Zapier o Activepieces è usare i webhook.

Webhook?

I webhook permettono di collegare applicazioni tra loro inviando dati in tempo reale da un'applicazione all'altra ogni volta che si verifica un determinato evento.

In SimplePDF, ogni volta che un PDF viene inviato tramite il portale della tua azienda, sia usando i link dei moduli che integrandolo nel tuo sito web, viene inviato un evento contenente il nome del documento, un link al PDF compilato e un link ai dati strutturati del modulo tra le altre informazioni.

I dati strutturati del modulo sono la parte a cui tiene di più la maggior parte delle integrazioni: invece di analizzare il PDF compilato, ricevi ogni risposta in formato JSON, pronta per essere archiviata, instradata o trasmessa a un altro sistema. Vedi Estrarre i dati strutturati del modulo più sotto.

Da lì, il limite è il cielo e puoi dare libero sfogo alla tua immaginazione.

Potresti ad esempio salvare quelle informazioni in un foglio Google o integrarle con Zapier o Activepieces e sbloccare ancora più possibilità!

Configurare i webhook in SimplePDF

La configurazione dei webhook è disponibile con il piano BASIC

• Accedi al tuo account
• Vai alla vista delle impostazioni dell'account

• Fai clic su Update configuration
• Inserisci l'URL del webhook del servizio o dell'applicazione a cui vuoi inviare gli eventi

• Facoltativo: specifica gli header da inviare come parte del webhook

Ecco fatto! Un evento verrà inviato ogni volta che c'è una nuova compilazione

Eventi webhook

Di seguito troverai gli eventi inviati da SimplePDF al webhook che hai configurato.

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"
  }
}

Estrarre i dati strutturati del modulo

field_data_url è un link di breve durata ai dati del modulo della compilazione in formato JSON, così non devi mai analizzare il PDF compilato per leggere le risposte.

Cattura ogni campo, che si tratti di un campo integrato nel PDF (un campo modulo nativo, chiamato anche AcroField) o di un campo che il tuo destinatario ha compilato e che hai aggiunto sopra il documento in SimplePDF. Entrambi appaiono nello stesso elenco, ciascuno con il proprio id, il proprio name e il value inviato:

{
  "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" }
  ]
}

Ogni value è testo semplice (una firma o un'immagine viaggia come immagine incorporata). Poiché ogni voce porta sia l'id che il name, puoi associare ogni risposta al suo campo e inserirla direttamente in un foglio di calcolo, in un database o in un modulo a valle come una risposta a un questionario FHIR. Lo stesso identico JSON può essere rinviato a SimplePDF per precompilare un altro documento, così una compilazione completa il ciclo in modo pulito.

I campi di un documento sono stabili e sei tu a controllare come viene denominato ciascuno: configura i tuoi campi una volta sola (rinominali, contrassegnali come obbligatori, imposta i valori predefiniti) e ogni compilazione futura arriverà con lo stesso id e lo stesso name. Questo trasforma l'associazione dei dati del webhook al tuo sistema in una configurazione una tantum che poi funziona senza modifiche per ogni compilazione. (name è null per un campo che hai aggiunto sopra il documento ma che non hai mai denominato.)

field_data_url scade dopo 15 minuti, come url. Se ti serve più tardi, recuperane uno nuovo dall'API con GET /documents/{document_id}/submissions/{submission_id}. È null per le compilazioni acquisite prima che i dati strutturati del modulo fossero disponibili.

Informazioni sul contesto

Quando integri SimplePDF nel tuo sito web, potresti voler associare informazioni aggiuntive alle compilazioni.

Ad esempio, potresti voler:

• Sapere se la compilazione è stata avviata da un ambiente di sviluppo (environment) rispetto a uno di production.
• Inviare dettagli aggiuntivi su chi ha compilato il modulo (come un utente connesso) che ti faciliteranno l'elaborazione della compilazione.

Scopri come specificare un context nella documentazione di SimplePDF embed

Playground

A SimplePDF ci piacciono gli esempi, quindi che ne dici di un esempio reale di come funzionano i webhook?

1. Modifica il contesto qui sotto (fai clic per modificare il contenuto)

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

2. Invia questo modulo

3. Il webhook inviato da SimplePDF apparirà qui

Se hai domande, non esitare a contattarci all'indirizzo support@simplepdf.com