API de Webhooks

Configure webhooks por formulário e globais para notificações de respostas em tempo real.

Webhooks permitem que você receba notificações HTTP POST em tempo real quando os formulários recebem novos envios. O NueForm oferece suporte a dois níveis de webhooks:

Webhooks de formulário -- Uma única URL por formulário que recebe os envios daquele formulário específico.
Webhooks globais -- Até 5 URLs que recebem os envios de todos os seus formulários.

Webhooks exigem um plano Pro ou superior. Tentar usar os endpoints de webhook em um plano gratuito retornará um erro 403.

Todos os corpos de requisição e resposta usam nomes de campo em snake_case.

Endpoints

GET/api/v1/forms/:id/webhooksPUT/api/v1/forms/:id/webhooksGET/api/v1/webhooksPUT/api/v1/webhooksGET/api/v1/webhooks/secretPOST/api/v1/webhooks/secret

Obter Webhook do Formulário

GET/api/v1/forms/:id/webhooks

Recupera a URL do webhook configurada para um formulário específico.

Parâmetros de Caminho

idstringobrigatório

O ID do formulário

Se nenhum webhook estiver configurado, webhook_url será null.

Resposta

json

{
  "webhook_url": "https://example.com/hooks/nueform"
}

Exemplos de Código

bash

curl -X GET "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

Definir Webhook do Formulário

PUT/api/v1/forms/:id/webhooks

Define ou remove a URL do webhook de um formulário específico. Quando um envio é recebido, o NueForm enviará um HTTP POST para essa URL com os dados da resposta.

Parâmetros de Caminho

idstringobrigatório

O ID do formulário

Corpo da Requisição

urlstring or nullobrigatório

A URL do webhook. Deve ser uma URL válida. Defina como null para remover o webhook.

Exemplo de Requisição

json

{
  "url": "https://example.com/hooks/nueform"
}

Para remover um webhook:

json

{
  "url": null
}

Resposta

json

{
  "webhook_url": "https://example.com/hooks/nueform"
}

Exemplos de Código

bash

curl -X PUT "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/nueform" }'

Listar Webhooks Globais

GET/api/v1/webhooks

Recupera todos os webhooks globais configurados na sua conta. Webhooks globais são disparados para cada envio de formulário em todos os seus formulários.

Resposta

json

{
  "webhooks": [
    {
      "url": "https://example.com/hooks/all-forms",
      "enabled": true
    },
    {
      "url": "https://backup.example.com/hooks/nueform",
      "enabled": false
    }
  ]
}

Exemplos de Código

bash

curl -X GET "https://api.nueform.io/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

Definir Webhooks Globais

PUT/api/v1/webhooks

Substitui todos os webhooks globais pelo array fornecido. Você pode configurar até 5 webhooks globais. Cada webhook pode ser ativado ou desativado individualmente.

Corpo da Requisição

webhooksarrayobrigatório

Array de objetos de webhook (máximo 5)

Exemplo de Requisição

json

{
  "webhooks": [
    {
      "url": "https://example.com/hooks/all-forms",
      "enabled": true
    },
    {
      "url": "https://slack-webhook.example.com/nueform",
      "enabled": true
    },
    {
      "url": "https://backup.example.com/hooks/nueform",
      "enabled": false
    }
  ]
}

Resposta

json

{
  "webhooks": [
    {
      "url": "https://example.com/hooks/all-forms",
      "enabled": true
    },
    {
      "url": "https://slack-webhook.example.com/nueform",
      "enabled": true
    },
    {
      "url": "https://backup.example.com/hooks/nueform",
      "enabled": false
    }
  ]
}

Exemplos de Código

bash

curl -X PUT "https://api.nueform.io/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhooks": [
      { "url": "https://example.com/hooks/all-forms", "enabled": true },
      { "url": "https://backup.example.com/hooks/nueform", "enabled": false }
    ]
  }'

Obter Segredo do Webhook

GET/api/v1/webhooks/secret

Recupera o segredo de assinatura do seu webhook. Se ainda não existir um segredo, um é gerado automaticamente. O segredo é uma string hexadecimal de 64 caracteres derivada de 32 bytes aleatórios.

Use esse segredo para verificar se as requisições de webhook recebidas são genuinamente do NueForm, validando a assinatura HMAC-SHA256 no cabeçalho X-NueForm-Signature.

Quando o NueForm envia um webhook, ele inclui um cabeçalho X-NueForm-Signature contendo um digest hexadecimal HMAC-SHA256 do corpo da requisição. Verifique-o no seu handler de webhook para garantir a autenticidade.

Resposta

json

{
  "secret": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
}

Exemplos de Verificação de Assinatura

javascript

const crypto = require("crypto");

function verifyWebhookSignature(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Exemplos de Código

bash

curl -X GET "https://api.nueform.io/api/v1/webhooks/secret" \
  -H "Authorization: Bearer YOUR_API_KEY"

Regenerar Segredo do Webhook

POST/api/v1/webhooks/secret

Gera um novo segredo de assinatura de webhook, substituindo o existente. Após a regeneração, todas as entregas de webhook serão assinadas com o novo segredo.

Após regenerar, atualize seus receptores de webhook imediatamente para usar o novo segredo. Requisições assinadas com o segredo antigo falharão na verificação.

Resposta

json

{
  "secret": "f0e1d2c3b4a5968778695a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d"
}

Exemplos de Código

bash

curl -X POST "https://api.nueform.io/api/v1/webhooks/secret" \
  -H "Authorization: Bearer YOUR_API_KEY"

Formato do Payload do Webhook

Quando um formulário recebe um envio, o NueForm envia uma requisição POST para as URLs de webhook configuradas com o payload a seguir.

O campo event identifica o tipo de evento, e o objeto response contém os dados completos do envio, incluindo todas as respostas.

Cabeçalhos

Content-Typeapplication/json

Tipo de conteúdo do corpo da requisição

X-NueForm-Signaturestring

Digest hexadecimal HMAC-SHA256 do corpo da requisição

X-NueForm-Eventstring

Tipo de evento (por exemplo, response.submitted)

Exemplo de Payload

json

{
  "event": "response.submitted",
  "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "form_title": "Customer Feedback Survey",
  "response": {
    "id": "667a1b2c3d4e5f6a7b8c9d01",
    "submitted_at": "2026-02-27T15:42:00.000Z",
    "completed_at": "2026-02-27T15:45:30.000Z",
    "answers": [
      {
        "question_id": "66a1b2c3d4e5f6a7b8c9d001",
        "question_title": "What is your name?",
        "value": "Jane Smith"
      }
    ]
  }
}

Respostas de Erro

Respostas de erro padrão retornadas pelos endpoints de webhook.

Códigos de Erro

400Bad Request

Formato de URL inválido, máximo de 5 webhooks globais excedido ou campos obrigatórios ausentes

401Unauthorized

Chave de API ausente ou inválida

403Forbidden

Webhooks exigem um plano Pro ou superior

404Not Found

Formulário não encontrado

500Server Error

Erro interno do servidor

Exemplo de Erro

json

{
  "error": "Webhooks require a Pro plan or higher"
}

Última atualização: 20 de julho de 2026