Webhooks

Aprende cómo integrar notificaciones en tiempo real en tu aplicación

¿Qué son los webhooks?

Los webhooks son mensajes automáticos enviados desde aplicaciones cuando algo sucede. Tienen un mensaje—o payload—y se envían a una URL única (tu endpoint).

En lugar de verificar constantemente nuestra API en busca de nuevos datos (polling), los webhooks envían datos a tu aplicación en tiempo real cuando ocurren eventos. Esto es más eficiente y proporciona notificaciones instantáneas.

Cuando un usuario envía una encuesta o formulario en tu sitio web, Ask Users puede notificar instantáneamente a tu aplicación a través de webhook, permitiéndote:

Sincronizar automáticamente datos con tu CRM (Salesforce, HubSpot, etc.)
Enviar notificaciones a tu equipo a través de Slack o email
Activar flujos de trabajo personalizados en tu aplicación
Actualizar tu base de datos en tiempo real
Alimentar datos a plataformas de análisis

Cómo funcionan los webhooks

Evento ocurre

Un usuario envía una encuesta o formulario en tu sitio web. Ask Users captura este evento y se prepara para notificar a tu aplicación.

Webhook activado

Ask Users verifica qué webhooks están configurados para este evento. Si tu webhook está configurado para recibir este tipo de evento, preparamos el payload con todos los datos relevantes.

Petición HTTP POST enviada

Enviamos una petición HTTP POST a tu URL de webhook con los datos del evento en formato JSON. La petición incluye cabeceras de seguridad (firma HMAC) para verificar autenticidad.

Tu endpoint procesa los datos

Tu aplicación recibe el webhook, verifica la firma y procesa los datos. Puedes almacenarlos en tu base de datos, activar notificaciones, actualizar registros o realizar cualquier lógica personalizada.

Respuesta y reintento

Tu endpoint debe responder con un código de estado 2xx (típicamente 200 OK) en 30 segundos. Si no recibimos una respuesta exitosa, reintentaremos automáticamente la entrega hasta 5 veces con backoff exponencial:

Intento 1: Inmediato
Intento 2: 1 minuto después
Intento 3: 5 minutos después
Intento 4: 15 minutos después
Intento 5: 1 hora después
Intento 6: 6 horas después

Características clave

Entrega segura

Todos los webhooks están firmados con firmas HMAC-SHA256 para verificar autenticidad

Reintentos automáticos

Las entregas fallidas se reintentan automáticamente hasta 5 veces con backoff exponencial

Entrega en tiempo real

Los webhooks se activan inmediatamente cuando ocurren eventos, típicamente en milisegundos

Deduplicación de eventos

Los IDs únicos de eventos previenen el procesamiento duplicado incluso durante reintentos

Eventos soportados

`survey.response.created`

Activado cuando se envía una nueva respuesta de encuesta. Contiene los datos completos de la respuesta, incluyendo todas las respuestas, información del encuestado y metadatos de la encuesta.

`form.submission.created`

Activado cuando se crea un nuevo envío de formulario. Incluye todos los datos de los campos del formulario, estado de envío y detalles de configuración del formulario.

Inicio rápido

Configurar webhook en el panel

1. Ve a tu panel

2. Navega a Configuración → Webhooks

3. Haz clic en Crear Webhook

4. Ingresa la URL de tu endpoint y selecciona tipos de eventos

5. Guarda y copia tu clave secreta

Prueba tu webhook

Envía una encuesta o formulario de prueba para activar tu webhook y verificar que funciona correctamente. Revisa los registros de entrega en tu panel para ver la petición y respuesta.

Implementación de referencia de webhook

Aquí hay un ejemplo completo de cómo crear y verificar un endpoint de webhook en tu aplicación:

// Node.js/Express example
const crypto = require('crypto');

app.post('/webhooks/askusers', (req, res) => {
  const signature = req.headers['x-webhook-signature'];

  // Verify signature (see security section)
  if (!verifySignature(req.body, signature)) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook
  const { event_type, data } = req.body;

  // Return 200 OK immediately
  res.status(200).send('OK');

  // Process async
  processWebhookAsync(event_type, data);
});

Ejemplo de payload de webhook

Aquí hay un ejemplo de cómo se ve un payload de webhook:

{
  "event_type": "survey.response.created",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "data": {
    "response": {
      "id": "response-uuid",
      "survey_id": "survey-uuid",
      "response_data": {
        "question-id-1": "Answer 1",
        "question-id-2": "Answer 2"
      },
      "completion_status": "completed",
      "created_at": "2025-01-15T10:30:00.000Z"
    },
    "survey": {
      "id": "survey-uuid",
      "title": "Product Feedback Survey"
    }
  }
}

Seguridad y verificación

Siempre verifica las firmas de webhook para asegurar que las peticiones provienen de Ask Users. Cada webhook incluye una cabecera X-Webhook-Signature con una firma HMAC-SHA256.

Ejemplo de verificación (Node.js)

const crypto = require('crypto');

function verifySignature(payload, signature) {
  const secret = process.env.ASKUSERS_WEBHOOK_SECRET;
  const payloadString = JSON.stringify(payload);

  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payloadString)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Ejemplo de verificación (Python)

import hmac
import hashlib
import os

def verify_signature(payload: str, signature: str) -> bool:
    secret = os.environ['ASKUSERS_WEBHOOK_SECRET']

    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected_signature)

Mejores prácticas

1. Responde rápidamente

Siempre devuelve 200 OK inmediatamente, luego procesa el webhook de forma asíncrona. Mantén el tiempo de respuesta por debajo de 30 segundos para evitar timeouts.

2. Maneja entregas duplicadas

Usa el event_id para deduplicar eventos. Almacena IDs de eventos procesados para prevenir procesamiento duplicado. Esto es importante porque los reintentos pueden causar que el mismo evento se entregue múltiples veces.

3. Usa HTTPS

Siempre usa URLs HTTPS para endpoints de webhook en producción para garantizar seguridad de datos y prevenir ataques man-in-the-middle.

4. Monitorea registros de entrega

Revisa tus registros de entrega de webhook en el panel para monitorear tasas de éxito e identificar problemas. Los registros muestran la petición/respuesta completa para troubleshooting.

5. Implementa manejo adecuado de errores

Envuelve tu lógica de procesamiento de webhook en bloques try-catch y registra errores. Devuelve códigos de estado HTTP apropiados: 200-299 para éxito, 4xx para errores del cliente (que no se reintentarán), 5xx para errores del servidor (que activarán reintentos).

Integración sin código

¿No quieres escribir código? Usa webhooks con Zapier o Make:

Crea un nuevo trigger "Catch Webhook" en Zapier o Make
Copia la URL del webhook proporcionada
Crea un webhook en Ask Users con esa URL
Pruébalo enviando un formulario o encuesta
¡Construye tu flujo de trabajo de automatización!

¿Necesitas ayuda?

Si tienes preguntas o necesitas asistencia con webhooks:

• Revisa los registros de entrega en tu panel
• Revisa la sección de troubleshooting arriba
• Contáctanos en support@askusers.org