Como configurar webhooks para ser notificado de novas submissões de formulários PDF

Benjamin André-Micolon

Uma forma poderosa de enviar as submissões para a sua aplicação ou ligar o SimplePDF a outros serviços como o Zapier ou o Activepieces é utilizar webhooks.

Webhooks?

Os webhooks permitem ligar aplicações entre si, enviando dados em tempo real de uma aplicação para outra(s) sempre que um determinado evento ocorre.

No SimplePDF, sempre que um PDF é submetido através do portal da sua empresa, seja usando ligações de formulário ou incorporação no seu website, é enviado um evento contendo o nome do documento, uma ligação para o PDF preenchido e uma ligação para os dados estruturados do formulário, entre outras informações.

Os dados estruturados do formulário são a parte que mais importa à maioria das integrações: em vez de analisar o PDF preenchido, recebe cada resposta em JSON, pronta para armazenar, encaminhar ou canalizar para outro sistema. Consulte Extrair os dados estruturados do formulário mais abaixo.

A partir daí, o céu é o limite e pode deixar a imaginação correr livremente.

Pode, por exemplo, guardar essa informação numa folha do Google Sheets ou integrá-la com o Zapier ou o Activepieces e desbloquear ainda mais possibilidades!

Configurar webhooks no SimplePDF

A configuração de webhooks está disponível com o plano BASIC

• Inicie sessão na sua conta
• Navegue até à vista de definições da conta

• Clique em Update configuration
• Introduza o URL do webhook do serviço ou aplicação para o qual pretende enviar eventos

• Opcional: especifique os cabeçalhos a enviar como parte do webhook

E pronto! Um evento será enviado sempre que houver uma nova submissão

Eventos de webhook

Abaixo encontra os eventos que são enviados pelo SimplePDF para o webhook que configurou.

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

Extrair os dados estruturados do formulário

field_data_url é uma ligação de curta duração para os dados do formulário da submissão em formato JSON, para que nunca tenha de analisar o PDF preenchido para ler as respostas.

Captura todos os campos, quer se trate de um campo integrado no PDF (um campo de formulário nativo, também chamado AcroField) ou de um campo que o seu destinatário preencheu e que adicionou sobre o documento no SimplePDF. Ambos aparecem na mesma lista, cada um com o seu id, o seu name e o value submetido:

{
  "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 é texto simples (uma assinatura ou imagem é transportada como imagem incorporada). Como cada entrada contém tanto o id como o name, pode associar cada resposta ao respetivo campo e introduzi-la diretamente numa folha de cálculo, numa base de dados ou num formulário a jusante, como uma resposta a um questionário FHIR. Esse mesmo JSON pode ser reenviado para o SimplePDF para preencher previamente outro documento, de modo que uma submissão completa o ciclo de forma limpa.

Os campos de um documento são estáveis e é o utilizador que controla como cada um é nomeado: configure os seus campos uma vez (mude-lhes o nome, marque-os como obrigatórios, defina valores predefinidos) e cada submissão futura chegará com o mesmo id e o mesmo name. Isto transforma a associação dos dados do webhook ao seu próprio sistema numa configuração única que depois funciona sem alterações para cada submissão. (name é null para um campo que adicionou sobre o documento mas que nunca nomeou.)

field_data_url expira após 15 minutos, tal como url. Se precisar dele mais tarde, obtenha um novo a partir da API com GET /documents/{document_id}/submissions/{submission_id}. É null para submissões registadas antes de os dados estruturados do formulário estarem disponíveis.

Sobre o contexto

Quando integra o SimplePDF no seu website, pode querer associar informação adicional às submissões.

Por exemplo, pode querer:

• Saber se a submissão foi iniciada a partir de um ambiente de development vs um de production.
• Enviar detalhes adicionais sobre quem submeteu o formulário (como um utilizador autenticado) para facilitar o processamento da submissão.

Saiba como especificar um context na documentação do SimplePDF embed

Playground

No SimplePDF gostamos de exemplos, então que tal um exemplo real de como os webhooks funcionam?

1. Modifique o contexto abaixo (clique para editar o conteúdo)

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

2. Submeta este formulário

3. O webhook enviado pelo SimplePDF aparecerá aqui

Se tiver alguma questão, não hesite em contactar support@simplepdf.com