Cómo configurar webhooks para recibir notificaciones de nuevos envíos de formularios PDF

Benjamin André-Micolon

Una forma potente de enviar los envíos a su aplicación o conectar SimplePDF con otros servicios como Zapier o Activepieces es usar webhooks.

¿Webhooks?

Los webhooks permiten conectar aplicaciones entre sí enviando datos en tiempo real de una aplicación a otra(s) cada vez que ocurre un evento determinado.

En SimplePDF, cada vez que se envía un PDF a través de su portal de empresa, ya sea usando enlaces de formulario o integración en su sitio web, se envía un evento que contiene el nombre del documento, un enlace al PDF rellenado y un enlace a los datos estructurados del formulario entre otras cosas.

Los datos estructurados del formulario son la parte que más importa a la mayoría de las integraciones: en lugar de analizar el PDF rellenado, recibe cada respuesta como JSON, lista para almacenar, enrutar o canalizar hacia otro sistema. Consulte Extraer los datos estructurados del formulario más abajo.

A partir de ahí, las posibilidades son infinitas y puede dejar volar su imaginación.

Podría, por ejemplo, guardar esa información en una hoja de Google o integrarlo con Zapier o Activepieces y desbloquear aún más posibilidades.

Configurar webhooks en SimplePDF

La configuración de webhooks está disponible con el plan BASIC

• Inicie sesión en su cuenta
• Navegue a la vista de configuración de la cuenta

• Haga clic en Update configuration
• Introduzca la URL del webhook del servicio o aplicación al que desea enviar eventos

• Opcional: especifique los headers a enviar como parte del webhook

¡Eso es todo! Se enviará un evento cada vez que haya un nuevo envío

Eventos de webhook

A continuación encontrará los eventos que SimplePDF envía al webhook que 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"
  }
}

Extraer los datos estructurados del formulario

field_data_url es un enlace de corta duración a los datos del formulario del envío en formato JSON, de modo que nunca tiene que analizar el PDF rellenado para leer las respuestas.

Captura cada campo, ya sea un campo integrado en el PDF (un campo de formulario nativo, también llamado AcroField) o un campo que su destinatario rellenó y que usted añadió sobre el documento en SimplePDF. Ambos aparecen en la misma lista, cada uno con su id, su name y el value enviado:

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

Cada value es texto plano (una firma o una imagen viaja como imagen incrustada). Como cada entrada lleva tanto el id como el name, puede asociar cada respuesta a su campo e introducirla directamente en una hoja de cálculo, una base de datos o un formulario posterior como una respuesta de cuestionario FHIR. Ese mismo JSON puede enviarse de vuelta a SimplePDF para rellenar previamente otro documento, de modo que un envío completa el ciclo sin problemas.

Los campos de un documento son estables y usted controla cómo se nombra cada uno: configure sus campos una vez (renómbrelos, márquelos como obligatorios, establezca valores predeterminados) y cada envío futuro llegará con el mismo id y el mismo name. Eso convierte la asociación de los datos del webhook con su propio sistema en una configuración única que luego funciona sin cambios para cada envío. (name es null para un campo que añadió sobre el documento pero que nunca nombró.)

field_data_url caduca después de 15 minutos, igual que url. Si lo necesita más adelante, obtenga uno nuevo desde la API con GET /documents/{document_id}/submissions/{submission_id}. Es null para los envíos capturados antes de que los datos estructurados del formulario estuvieran disponibles.

Sobre el contexto

Cuando integra SimplePDF en su sitio web, puede querer asociar información adicional a los envíos.

Por ejemplo, puede querer:

• Saber si el envío fue iniciado desde un entorno de desarrollo (environment) o uno de producción (production).
• Enviar detalles adicionales sobre quién envió el formulario (como un usuario con sesión iniciada) que le faciliten el procesamiento del envío.

Aprenda cómo especificar un context en la documentación de SimplePDF embed

Zona de pruebas

En SimplePDF nos gustan los ejemplos, así que ¿qué tal un ejemplo real de cómo funcionan los webhooks?

1. Modifique el contexto a continuación (haga clic para editar el contenido)

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

2. Envíe este formulario

3. El webhook enviado por SimplePDF aparecerá aquí

Si tiene alguna pregunta, no dude en contactarnos en support@simplepdf.com