Webhooks

O Formgong envia um POST JSON e uma assinatura HMAC-SHA256 do corpo em bruto. O segredo está nas definições do formulário. Até 5 tentativas; as repetições esperam 30 s, 2 min, 10 min e 30 min.

Se a última tentativa também falhar, a Formgong envia um email ao dono do formulário. O mesmo email é enviado quando, após essas tentativas, falha um webhook do Slack ou do Discord, qualquer outro webhook, o Google Sheets ou o Telegram. No máximo um email por dia por formulário e canal, em qualquer plano, incluindo o Free. O email do Telegram diz o problema em palavras simples (por exemplo, o bot foi removido do grupo, o chat não foi encontrado ou o utilizador bloqueou o bot) e como voltar a ligar: crie um código novo nas definições do formulário, abra a ligação do bot ou adicione o bot ao grupo e envie /connect com esse código.

{
  "event": "submission.created",
  "form": { "id": "…", "name": "…" },
  "submission": {
    "id": "…",
    "created_at": "2026-09-29T12:00:00.000Z",
    "page_url": "https://example.com/",
    "fields": { "name": "Inês", "email": "ines@example.pt" },
    "is_spam": false
  }
}

Header X-Signature: sha256=…. Header X-Formgong-Event: submission.created.

import { createHmac, timingSafeEqual } from "node:crypto";

function verified(rawBody, signature, secret) {
  const digest = createHmac("sha256", secret).update(rawBody).digest();
  const got = Buffer.from(String(signature).replace(/^sha256=/, ""), "hex");
  return got.length === digest.length && timingSafeEqual(got, digest);
}

Links de ficheiros nos webhooks

Cada ficheiro enviado no webhook recebe um download_url assinado que abre sem iniciar sessão até expirar. Qualquer pessoa com o link pode descarregar o ficheiro, por isso ative isto só se o serviço que recebe o seu webhook precisar dos ficheiros. Desligar, renovar o segredo do webhook ou apagar o envio para os links de imediato.

Para ativar, abra as definições do formulário, aceite anexos e depois, na secção de webhooks, escolha 24 horas ou 7 dias em «Links de ficheiros nos webhooks» e guarde. Só os webhooks enviados depois disso levam os links.

"attachments": [{
  "id": "…", "field": "photo", "filename": "cart.jpg", "size": 182044, "content_type": "image/jpeg",
  "url": "https://formgong.com/dashboard/forms/…/attachments/…",
  "download_url": "https://formgong.com/files/…?exp=…&sig=…",
  "download_expires_at": "2026-11-02T12:00:00.000Z"
}]

A partir daí cada ficheiro em submission.attachments traz também download_url e download_expires_at. O serviço que recebe o webhook descarrega o ficheiro com um pedido GET simples, sem cabeçalhos nem login. Depois do prazo o link devolve 404, e cada ficheiro pode ser descarregado até 60 vezes por hora. E-mails, Telegram e mensagens do Slack ou Discord nunca recebem estes links.

Slack e Discord

Cole no campo do webhook um URL de webhook de entrada do Slack (https://hooks.slack.com/services/…) ou de webhook de um canal do Discord (https://discord.com/api/webhooks/…). A Formgong passa a enviar, em vez do JSON acima, uma mensagem curta de chat com o nome do formulário, as respostas, a página e uma ligação para o envio.

Menções como @everyone, @here e @channel são neutralizadas, um visitante não consegue esconder uma ligação atrás de outro texto e envios longos são cortados aos limites da plataforma com uma ligação para o envio completo. Os ficheiros aparecem pelo nome. O cabeçalho X-Signature continua a ser enviado, as novas tentativas e o registo de entregas funcionam como em qualquer webhook, e «Enviar teste» mostra o aspeto da mensagem.

As ligações de fluxos de trabalho do Slack (hooks.slack.com/triggers/…) e todos os outros URL recebem o JSON.

Make, n8n, Zapier

Crie um módulo de webhook (Make), um Webhook node (n8n) ou um Catch Hook (Zapier) e cole esse URL nas definições do formulário. A partir daí, associe submission.fields.

Receitas passo a passo (em inglês): Make, n8n, Zapier, KeyCRM.

Google Sheets

// Webhook URL: the web app URL + "?key=" + the same SECRET (Apps Script cannot read headers).
const SECRET = "change-me";

function doPost(e) {
  if (e.parameter.key !== SECRET) return reply();
  const body = JSON.parse(e.postData.contents);
  if (body.event !== "submission.created") return reply(); // the dashboard test sends "webhook.test"
  const lock = LockService.getScriptLock();
  lock.waitLock(20000);
  try {
    const sheet = SpreadsheetApp.getActive().getSheetByName("Leads");
    const id = body.submission.id;
    // A retry after a timeout carries the same id: skip rows that are already there.
    if (!sheet.getRange("A:A").createTextFinder(id).matchEntireCell(true).findNext()) {
      const fields = body.submission.fields;
      sheet.appendRow([id, body.submission.created_at, fields.name, fields.email, fields.message]);
    }
  } finally {
    lock.releaseLock();
  }
  return reply();
}

// HtmlService, not ContentService: ContentService answers with a redirect, and a webhook counts a redirect as a failure.
function reply() {
  return HtmlService.createHtmlOutput("ok");
}

KeyCRM

Não há conector nativo. No n8n ou no Make, receba o webhook do Formgong e chame a API da KeyCRM com a sua própria chave. Os campos estão em submission.fields.

KeyCRM: Receitas passo a passo (em inglês)