API de Webhooks

Configura webhooks por formulario y globales para notificaciones de respuestas en tiempo real.

Los webhooks te permiten recibir notificaciones HTTP POST en tiempo real cuando los formularios reciben nuevos envíos. NueForm soporta dos niveles de webhooks:

Webhooks de formulario -- Una URL única por formulario que recibe envíos de ese formulario específico.
Webhooks globales -- Hasta 5 URLs que reciben envíos de todos tus formularios.

Los webhooks requieren un plan Pro o superior. Intentar usar los endpoints de webhooks en un plan gratuito devolverá un error 403.

Todos los cuerpos de solicitud y respuesta utilizan nombres de campo en 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

Obtener Webhook del Formulario

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

Obtiene la URL del webhook configurada para un formulario específico.

Parámetros de Ruta

idstringobligatorio

El ID del formulario

Si no hay webhook configurado, webhook_url será null.

Respuesta

json

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

Ejemplos de Código

bash

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

Configurar Webhook del Formulario

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

Establece o elimina la URL del webhook para un formulario específico. Cuando se recibe un envío, NueForm enviará un HTTP POST a esta URL con los datos de la respuesta.

Parámetros de Ruta

idstringobligatorio

El ID del formulario

Cuerpo de Solicitud

urlstring or nullobligatorio

La URL del webhook. Debe ser una URL válida. Establece a null para eliminar el webhook.

Ejemplo de Solicitud

json

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

Para eliminar un webhook:

json

{
  "url": null
}

Respuesta

json

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

Ejemplos 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 Globales

GET/api/v1/webhooks

Obtiene todos los webhooks globales configurados para tu cuenta. Los webhooks globales se activan para cada envío de formulario en todos tus formularios.

Respuesta

json

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

Ejemplos de Código

bash

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

Configurar Webhooks Globales

PUT/api/v1/webhooks

Reemplaza todos los webhooks globales con el array proporcionado. Puedes configurar hasta 5 webhooks globales. Cada webhook puede ser habilitado o deshabilitado individualmente.

Cuerpo de Solicitud

webhooksarrayobligatorio

Array de objetos webhook (máx. 5)

Ejemplo de Solicitud

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

Respuesta

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

Ejemplos 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 }
    ]
  }'

Obtener Secreto de Webhook

GET/api/v1/webhooks/secret

Obtiene tu secreto de firma de webhooks. Si no existe un secreto aún, se genera uno automáticamente. El secreto es una cadena hexadecimal de 64 caracteres derivada de 32 bytes aleatorios.

Usa este secreto para verificar que las solicitudes de webhook entrantes provienen genuinamente de NueForm validando la firma HMAC-SHA256 en el encabezado X-NueForm-Signature.

Cuando NueForm envía un webhook, incluye un encabezado X-NueForm-Signature que contiene un digest hexadecimal HMAC-SHA256 del cuerpo de la solicitud. Verifica esto en tu manejador de webhooks para asegurar la autenticidad.

Respuesta

json

{
  "secret": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
}

Ejemplos de Verificación de Firma

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)
  );
}

Ejemplos de Código

bash

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

Regenerar Secreto de Webhook

POST/api/v1/webhooks/secret

Genera un nuevo secreto de firma de webhooks, reemplazando el existente. Después de la regeneración, todos los envíos de webhook se firmarán con el nuevo secreto.

Después de regenerar, actualiza tus receptores de webhook inmediatamente para usar el nuevo secreto. Las solicitudes firmadas con el secreto anterior fallarán en la verificación.

Respuesta

json

{
  "secret": "f0e1d2c3b4a5968778695a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d"
}

Ejemplos de Código

bash

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

Formato del Payload de Webhook

Cuando un formulario recibe un envío, NueForm envía una solicitud POST a las URLs de webhook configuradas con el siguiente payload.

El campo event identifica el tipo de evento, y el objeto response contiene los datos completos del envío incluyendo todas las respuestas.

Encabezados

Content-Typeapplication/json

Tipo de contenido del cuerpo de la solicitud

X-NueForm-Signaturestring

Digest hexadecimal HMAC-SHA256 del cuerpo de la solicitud

X-NueForm-Eventstring

Tipo de evento (ej., response.submitted)

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

Respuestas de Error

Respuestas de error estándar devueltas por los endpoints de webhook.

Códigos de Error

400Bad Request

Formato de URL inválido, se excedió el máximo de 5 webhooks globales o campos requeridos faltantes

401Unauthorized

API key faltante o inválida

403Forbidden

Los webhooks requieren un plan Pro o superior

404Not Found

Formulario no encontrado

500Server Error

Error interno del servidor

Ejemplo de Error

json

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

Ultima actualizacion: 6 de abril de 2026