ID del formulario

Webhooks

Eventos y payloads de webhook, verificación de la firma HMAC-SHA256, orden, reintentos, protección de endpoints, reenvío y cabeceras personalizadas.

Los webhooks envían a tu servidor los eventos de tus envíos en cuanto ocurren: envíos nuevos, cambios a spam y de vuelta, y eliminaciones. Las entregas se firman con el esquema Standard Webhooks, se reintentan durante unos tres días y quedan registradas intento a intento en el panel. Tienes handlers listos en Recibir webhooks.

Para Slack, Discord, Telegram, Google Sheets, Notion, Airtable, HubSpot, Attio o Pipedrive no necesitas un webhook: añade una integración al formulario.

Añade un endpoint

  1. En el panel, abre Webhooks y elige Add endpoint.
  2. Escribe una URL HTTPS y elige un formulario, o todos los formularios del espacio de trabajo.
  3. Elige los eventos que recibe. Un endpoint nuevo recibe solo submission.created.
  4. Copia el secreto de firma. Empieza con whsec_ y solo se muestra completo una vez.
  5. Envía un evento de prueba para comprobar tu handler.

También puedes añadir, modificar, desactivar y eliminar endpoints con la API REST o con un agente de IA conectado al servidor MCP. Allí el secreto también se devuelve una sola vez.

URL de endpoints

  • Solo https:, en el puerto predeterminado 443, sin usuario ni contraseña en la URL, de hasta 2048 caracteres.
  • Un nombre de host público. Se rechazan las direcciones IP, localhost y los nombres que terminan en .local, .internal, .intranet, .lan, .home.arpa o .onion, igual que ikiform.com, workers.dev y pages.dev.
  • El nombre de host solo debe resolver a direcciones públicas. Se rechazan los rangos privados, de loopback, link-local y de NAT de operador.
  • La URL se comprueba al guardarla y otra vez antes de cada entrega. Un endpoint que empieza a resolver a una dirección privada se desactiva.
  • Un espacio de trabajo puede tener hasta 3 endpoints. Enterprise no tiene límite.

Eventos

Cada endpoint recibe solo los eventos a los que está suscrito. Cámbialos cuando quieras con Edit en el endpoint.

TipoSe envía cuandoSuscrito por defecto
submission.createdSe recibe un envío, o un envío marcado como spam se marca como no spamSí
submission.updatedUn envío pasa de recibido a spam, o al revés, en el panel o con la API RESTNo
submission.deletedSe elimina un envío en el panel o con la API RESTNo
submission.spamUn envío nuevo se guarda como spamNo
endpoint.testEliges Send test en la página del endpoint. Se envía una vez, sin reintentosSiempre
  • El spam no envía nada salvo que el endpoint esté suscrito a submission.spam. Los envíos retenidos porque el espacio de trabajo superó su límite no envían nada hasta que se liberan, y entonces envían submission.created.
  • Marcar un envío como no spam envía submission.updated y, además, submission.created a cada endpoint suscrito que nunca recibió uno para ese envío.
  • Marcar un envío como spam envía submission.updated y cancela sus entregas de submission.created que aún no han salido.
  • Eliminar un envío borra sus entregas anteriores y envía submission.deleted, que solo lleva ids, nunca valores de campos.

La petición

Cada entrega es un POST con un cuerpo JSON y tres cabeceras de firma, enviado desde el servicio de entregas de Ikiform con el user agent Ikiform-Webhooks/1.0.

Cabeceras
POST /webhooks/ikiform HTTP/1.1
content-type: application/json
user-agent: Ikiform-Webhooks/1.0
webhook-id: dlv_01k7v2d4n8r2p6s0w3y5b7c9e1
webhook-timestamp: 1792300000
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
CabeceraValor
webhook-idEl id de la entrega. Es el mismo en cada reintento de la misma entrega, así que úsalo para ignorar duplicados
webhook-timestampSegundos Unix en que se firmó este intento. Cambia en cada intento
webhook-signaturev1, más un HMAC-SHA256 en base64. Varios valores separados por espacios mientras se rota un secreto

Payloads

Todos los eventos tienen el mismo sobre: id, type, timestamp, api_version y data. El data de cada tipo:

{
  "id": "dlv_01k7v2d4n8r2p6s0w3y5b7c9e1",
  "type": "submission.created",
  "timestamp": "2026-10-17T12:00:00.000Z",
  "api_version": "2026-10-17",
  "data": {
    "submission_id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
    "sequence": 17922384000000,
    "form": { "id": "frm_xxxxxxxxxxxxxxxx", "name": "Contact" },
    "fields": { "name": "Ada", "email": "ada@example.com", "message": "Hello" },
    "meta": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "origin": "https://example.com",
      "referrer": "https://example.com/contact",
      "country": "GB",
      "subject": null,
      "reply_to": "ada@example.com"
    },
    "created_at": "2026-10-17T12:00:00.000Z",
    "truncated": false
  }
}
CampoDescripción
idEl id de la entrega, igual que webhook-id
typeEl tipo de evento
timestampCuándo se creó la entrega, en ISO 8601 UTC. Es el mismo en cada reintento
api_versionLa versión del payload con la que se creó el endpoint, actualmente 2026-10-17
data.submission_idEl id del envío. Obtenlo con la API REST
data.sequenceUn número que crece con cada cambio del envío. Úsalo para volver a ordenar las entregas
data.formEl id y el name del formulario
data.fieldsLos valores guardados. Con campos definidos, son los valores validados y convertidos
data.metaLas mismas claves que el meta de la API REST. Todas las claves están presentes y cualquier valor puede ser null. La IP del visitante y su hash nunca se envían
data.meta.user_agentEl user agent del navegador, de hasta 512 caracteres
data.meta.origin, referrerDe dónde vino el envío, cuando el navegador los envió
data.meta.countryCódigo de país de dos letras, de Cloudflare
data.meta.subject, reply_toDe los campos _subject y _replyto
data.created_atCuándo se guardó el envío
data.truncatedtrue cuando el cuerpo superaría los 256 KB, en cuyo caso fields está vacío
data.status, previous_statusEn submission.updated: el estado nuevo y el anterior, received o spam. En submission.spam: siempre spam
data.spamEn submission.spam: el score de spam y sus reasons, como honeypot o keyword
data.deleted_atEn submission.deleted, que no tiene fields, meta ni created_at

Cualquier valor de meta puede ser null. Trata los valores de los campos como entrada no confiable, igual que un envío de formulario a tu propio servidor.

Orden y duplicados

No se garantiza que las entregas lleguen en orden. Un reintento puede llegar después de un evento más reciente, y un endpoint lento puede ver un submission.updated antes del submission.created al que sigue. Dos valores lo hacen seguro:

ValorÚsalo para
webhook-idIgnorar duplicados. Es el mismo en cada reintento y en un reenvío, así que sirve como clave de idempotencia
data.sequenceOrdenar los eventos de un envío. Guarda el mayor que hayas aplicado por submission_id y omite cualquier entrega con un número menor o igual
app/api/webhooks/ikiform/route.ts
import { verifyWebhook } from "@ikiform/sdk/webhooks";

export async function POST(request: Request) {
  const event = await verifyWebhook({
    payload: await request.text(),
    headers: request.headers,
    secret: process.env.IKIFORM_WEBHOOK_SECRET!,
  });
  if (event.type === "endpoint.test") return new Response(null, { status: 204 });

  const status =
    event.type === "submission.deleted"
      ? "deleted"
      : event.type === "submission.created"
        ? "received"
        : event.data.status;

  await db.query(
    `insert into leads (submission_id, sequence, status, delivery_id)
     values ($1, $2, $3, $4)
     on conflict (submission_id) do update
       set sequence = excluded.sequence, status = excluded.status, delivery_id = excluded.delivery_id
       where leads.sequence < excluded.sequence`,
    [event.data.submission_id, event.data.sequence, status, event.id],
  );
  return new Response(null, { status: 204 });
}

La cláusula where aplica una entrega solo si es más reciente que lo guardado, así que un submission.created tardío no puede devolver un envío eliminado, y un reintento de una entrega ya aplicada no cambia nada.

Cabeceras personalizadas

Añade hasta 10 cabeceras fijas en Headers al crear o editar un endpoint, por ejemplo una cabecera Authorization que esperan Zapier, n8n o tu propio gateway. Se envían con cada entrega a ese endpoint, pruebas incluidas.

Cabeceras
POST /hooks/catch/123456/abcdef HTTP/1.1
content-type: application/json
user-agent: Ikiform-Webhooks/1.0
authorization: Bearer zap_live_…
x-source: ikiform
webhook-id: dlv_01k7v2d4n8r2p6s0w3y5b7c9e1
webhook-timestamp: 1792300000
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
  • Los nombres usan letras, números y guiones, hasta 64 caracteres. Los valores son ASCII imprimible en una línea, hasta 1024 caracteres.
  • Los valores se guardan cifrados y no se vuelven a mostrar. El endpoint y su registro de entregas solo muestran los nombres. Los nombres se guardan en texto plano, así que pon los secretos solo en los valores, nunca en los nombres. Deja vacío un valor guardado para conservarlo, o escribe uno nuevo para reemplazarlo.
  • Se rechazan las cabeceras que fija Ikiform o que controlan la conexión: content-type, content-length, user-agent, host, cookie y similares, y cualquier nombre que empiece por webhook-, cf-, x-forwarded-, proxy- o sec-. Las cabeceras propias de Ikiform siempre tienen prioridad.
  • Las cabeceras personalizadas no están cubiertas por la firma. Un token compartido demuestra menos que una firma, así que verifica también webhook-signature siempre que tu receptor pueda.

Verifica la firma

Cómo se calcula la firma del webhook
webhook-id.webhook-timestamp.cuerpo sin procesar

HMAC-SHA256, con el secreto decodificado de base64 después de whsec_ como clave

webhook-signature: v1,base64(signature)

  • Usa el cuerpo de la petición sin procesar, exactamente como llegó. Analizar y volver a serializar el JSON cambia los bytes.
  • La cabecera puede contener varias firmas separadas por espacios. Acepta la petición si coincide cualquier firma v1.
  • Compara en tiempo constante y rechaza las marcas de tiempo que se alejen más de 5 minutos de la hora actual.

Con el SDK

verifyWebhook hace todo lo anterior con Web Crypto y devuelve el evento ya analizado, o lanza WebhookVerificationError con un reason. Acepta un objeto Headers o un objeto simple como el req.headers de Node.

app/api/webhooks/ikiform/route.ts
import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";

export async function POST(request: Request) {
  const payload = await request.text();
  try {
    const event = await verifyWebhook({
      payload,
      headers: request.headers,
      secret: process.env.IKIFORM_WEBHOOK_SECRET!,
    });
    if (event.type === "submission.created") {
      console.log(event.data.fields);
    }
    return new Response(null, { status: 204 });
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      return new Response(error.reason, { status: 400 });
    }
    throw error;
  }
}

Sin el SDK

Cualquier librería de Standard Webhooks también funciona. A mano son unas pocas líneas:

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

const secret = Buffer.from(process.env.IKIFORM_WEBHOOK_SECRET.replace(/^whsec_/, ""), "base64");

export function verify(body, headers) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${id}.${timestamp}.${body}`).digest();
  return signatures.split(" ").some((entry) => {
    const [version, signature] = entry.split(",");
    if (version !== "v1" || !signature) return false;
    const received = Buffer.from(signature, "base64");
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
}

Verificador de firmas

Ignorar el margen de 5 minutos

Usa verifyWebhook del SDK con Web Crypto en tu navegador. Nada de lo que pegues sale de esta página.

Respuesta

Tu respuestaQué hace Ikiform
Cualquier 2xx en menos de 15 segundosMarca la entrega como correcta
410 GoneMarca la entrega como fallida y desactiva el endpoint al instante
429 o 503 con Retry-AfterReintenta después de ese tiempo, pero no más tarde que el siguiente paso del calendario
Una redirecciónNo se sigue. Cuenta como un fallo
Cualquier otro estado, un timeout o un error de redReintenta según el calendario de abajo

Haz el trabajo lento después de responder, por ejemplo en una cola. Los primeros 4 KB del cuerpo de tu respuesta se guardan en el registro de entregas.

Reintentos

Un intento fallido se reintenta según este calendario, cada espera con hasta un 20% de jitter aleatorio en cada sentido. Después del 9.º intento, unos 3 d 6 h después del primero, la entrega se marca como fallida.

Calendario de reintentos de webhook, con la espera antes de cada intento en escala logarítmica
IntentoEspera previaDesde el primero
  1. 1ahora0 s
  2. 25 s5 s
  3. 35 min5 min
  4. 430 min35 min
  5. 52 h2 h 35 min
  6. 65 h7 h 35 min
  7. 710 h17 h 35 min
  8. 81 d1 d 18 h
  9. 91 d 12 h3 d 6 h

Las barras oscuras muestran la espera más corta y las claras la más larga, con un jitter del 20% en cada sentido. Después del intento 9, la entrega se marca como fallida.

Protección de endpoints

Cuando un endpoint tiene problemas, Ikiform baja el ritmo en vez de insistir, y te avisa cuando se detiene o vuelve.

ProtecciónQué ocurre
ConcurrenciaComo máximo 5 peticiones a la vez hacia un mismo endpoint. El resto espera su turno
PausaTras 20 intentos fallidos seguidos, las entregas al endpoint se pausan 5 minutos. Cada pausa seguida dura el doble, hasta 1 hora. Un éxito la termina
DesactivaciónTras 5 días sin ninguna entrega correcta, el endpoint se desactiva y la dirección de notificaciones del espacio de trabajo, o sus propietarios, reciben un email
RecuperadoCuando un endpoint que llevaba una hora o más fallando vuelve a funcionar, la misma dirección recibe un email avisando de que se ha recuperado
  • Esperar un hueco libre o el final de una pausa no gasta ningún intento. La entrega conserva todos sus reintentos.
  • Los reintentos que lanzas a mano y los eventos de prueba se saltan la pausa, así puedes comprobar un arreglo al momento.
  • La página del endpoint muestra una línea cuando las entregas están en pausa, cuando tu servidor las rechaza con 4xx o cuando fallan.

Endpoints desactivados

Una respuesta 410 Gone o un destino que pasa a ser privado desactiva un endpoint al instante, y lo mismo 5 días de fallos. Un endpoint desactivado no recibe nada: los eventos nuevos no se ponen en cola para él y las entregas pendientes fallan. Vuelve a activarlo con Enabled en la página del endpoint cuando esté arreglado. Ikiform te ofrece entonces reenviar las entregas que fallaron desde que empezó a fallar, hasta 7 días atrás.

Reenviar entregas fallidas

Elige Replay failed deliveries en el menú del endpoint y escoge las últimas 24 horas, 3 días o 7 días. Cada entrega creada en ese intervalo que falló o se canceló se envía de nuevo en aproximadamente un minuto, hasta 1000 de una vez. Si el endpoint está en pausa, los reenvíos esperan a que termine. Los reenvíos conservan su webhook-id y su sequence originales, así que tus comprobaciones de duplicados y de orden siguen funcionando.

  • Una entrega que había agotado sus intentos recibe uno más. Una que se detuvo antes, por ejemplo porque el endpoint estaba desactivado, continúa su calendario de reintentos.
  • Se omiten las entregas de un formulario eliminado, y también los eventos que ya no corresponden a su envío: uno que se ha eliminado, o un submission.created de un envío que ahora es spam.
  • Cada reintento y cada reenvío manda exactamente el cuerpo del primer intento, byte a byte, aunque el envío, el nombre del formulario o la versión de la API hayan cambiado. Solo webhook-timestamp y webhook-signature son nuevos, firmados de nuevo para que tu verificación pase.
  • El endpoint debe estar activado. Los eventos de prueba nunca se reenvían.

Registros de entrega

La página de cada endpoint enumera sus entregas con su estado. Despliega una para ver cada intento: cuándo se ejecutó, si fue automático, manual o una prueba, el código de estado, la duración y los primeros 4 KB de tu respuesta o el error. Reintenta cualquier entrega desde ahí. Los intentos se conservan 30 días y las entregas 90 días.

Rotar secretos

Roll signing secret, o POST /webhooks/:endpointId/roll-secret, crea un secreto nuevo. Durante las siguientes 24 horas cada entrega se firma con el secreto antiguo y con el nuevo, así que webhook-signature contiene dos valores y puedes desplegar el nuevo secreto sin perder eventos.