Webhooks

Disponible en los planes Professional y Business

Formspree te permite configurar un webhook que se activará cada vez que un formulario reciba un nuevo envío. Los webhooks pueden usarse con funciones serverless, código de servidor personalizado u otros servicios de terceros, para realizar el manejo personalizado de los envíos del formulario.

Las funciones serverless ofrecen una forma ligera de procesar envíos de formularios. En lugar de crear un servidor web completo solo para procesar envíos de formularios, puedes crear una sola función serverless y desplegarla en una plataforma serverless. Hay varias plataformas para alojar funciones, como Cloudflare Workers, AWS Lambda y Google Cloud Functions. El ejemplo de abajo usa Cloudflare Workers, que ofrece un nivel gratuito generoso y un camino rápido del código a un endpoint desplegado.

Al habilitar tu plugin de Webhook se te pedirá seleccionar un tipo de webhook, ya sea Simple Webhook, Build Hook o REST Hook.

Simple Webhooks

Estos son webhooks normales. Simplemente enviaremos el payload a la URL deseada como solicitudes POST sin hacer preguntas.

Build Hooks

Estos son hooks que pueden usarse para activar nuevas builds en servicios de terceros como Netlify. Esto es básicamente un webhook con un cuerpo vacío.

REST Hooks

En caso de que lo necesites, también enviamos webhooks que cumplen con el protocolo REST Hooks. Eso es soportado por algunos servicios e involucra un handshake en el momento en que se crea el webhook.

Manejo del handshake de Resthook

Cuando eliges el protocolo Resthook, antes de que Formspree comience a enviar solicitudes de webhook, enviará una solicitud de confirmación con un encabezado X-Hook-Secret. Consulta los documentos de resthooks sobre seguridad para más información sobre el handshake de resthook.

Aquí hay un ejemplo de cómo manejar el handshake de resthook en un Cloudflare Worker, aunque los mismos conceptos aplican si lo estás implementando en tu propio servidor web.

export default {
  async fetch(request) {
    const url = new URL(request.url);
    if (url.pathname !== '/hook') {
      return new Response(url.pathname + '\n');
    }

    const hookSecret = request.headers.get('x-hook-secret');
    if (hookSecret) {
      // Step 1: Confirm the subscription. This request includes an
      // X-Hook-Secret header, and we echo it back to complete the
      // handshake.
      return new Response(null, {
        headers: { 'x-hook-secret': hookSecret },
      });
    }

    // Step 2: Receive webhook requests — do something with the payload!
    const payload = await request.json();
    console.log('Received webhook!', payload);
    return new Response(null, { status: 200 });
  },
};

En el Step 1 anterior, el Worker responde al handshake inicial de resthook con una respuesta que devuelve el encabezado x-hook-secret de la solicitud. El cuerpo está vacío.

El Step 2 es donde va tu funcionalidad personalizada. Cloudflare Workers se ejecutan en un V8 isolate con la API estándar fetch más bindings para KV, R2, D1 y queues — puedes persistir envíos, reenviarlos a otro servicio o activar cualquier acción downstream desde aquí. Consulta los documentos de Cloudflare Workers para detalles de despliegue y bindings.

Payload de Webhooks

Se envía un webhook en cada nuevo envío recibido.

Excepto por los Buildhooks (que están vacíos), el payload de los webhooks tiene la siguiente estructura:

{
  "form": "",
  "keys": ["keys", "in", "the", "order", "they", "were", "submitted"],
  "submission": {
    "_date": "2029-12-31T00:00:00",
    "field": "value",
    "other-fields": "other value"
  }
}