receptionworksAyuda

Integraciones y webhooks

Envía conversaciones, reservas, avisos al equipo y solicitudes de asistencia a Zapier, Make o a tu servidor; comprueba la firma y mira los envíos.

Las integraciones envían los eventos del negocio a otro servicio en el momento en que ocurren: una conversación nueva, una reserva, un aviso al equipo, una solicitud de asistencia. Con Zapier o Make puedes, por ejemplo, añadir una fila a una hoja de cálculo, enviar un mensaje a un chat o crear una ficha en un CRM sin copiar datos a mano.

Dónde encontrarlas

Abre «Módulos» en el menú superior, conecta el módulo «Integraciones» (está desactivado por defecto) y haz clic en «Abrir integraciones» en su tarjeta. Se abre la pestaña «Webhooks», y junto a ella está la pestaña «Registro de eventos». Solo Propietario y Administrador pueden abrir la sección: la dirección de un destino puede contener un token privado. Mientras el módulo está desactivado no se entrega nada, y los eventos ocurridos entretanto no se reenvían después. Los receptores siguen configurados y el registro de eventos sigue guardándose.

Cómo añadir un destino

  1. En Zapier crea un Zap con el disparador «Webhooks by Zapier» y el evento «Catch Hook» y copia la dirección que te da. En Make añade el módulo «Custom webhook» y copia su dirección.
  2. En la página de integraciones rellena «Nombre» (por ejemplo, el nombre del Zap) y «Dirección del destino» (la dirección copiada).
  3. En «Eventos que se envían» marca lo que se debe enviar.
  4. Haz clic en «Añadir destino».
  5. El secreto de firma aparece una sola vez. Cópialo y guárdalo. Zapier y Make no lo necesitan; tu propio servidor lo usa para comprobar la firma. Si lo pierdes, crea uno nuevo con «Cambiar el secreto».
  6. En la ficha del destino haz clic en «Enviar prueba». El resultado dice Entregado o No entregado con el motivo.

La dirección debe ser pública y empezar por https. Se rechazan, y la página indica el motivo: direcciones http, direcciones IP en lugar de un dominio, puertos personalizados, direcciones con usuario y contraseña, direcciones internas y direcciones de dominios de ReceptionWorks. La página muestra solo el dominio y la ruta: la parte tras el signo de interrogación puede contener el token de tu destino.

Qué eventos se envían

Los eventos del chat de prueba no se envían. Un destino recibe solo los eventos que ocurren después de añadirlo y mientras está activo: lo ocurrido durante una pausa o desactivación no se envía después.

«Mensaje nuevo» y «Conversación completa» llevan el texto íntegro de las conversaciones, incluido lo que escriben los clientes. El texto sale de ReceptionWorks y llega al destino que elija, así que márquelos solo para destinos de confianza. Un destino nuevo empieza con estos dos desmarcados. Solo se envían mientras algún destino los tenga marcados y no aparecen en el registro de eventos ni en su exportación: la propia conversación está en la bandeja de entrada. Los chats de prueba y los clientes bloqueados no se envían.

Qué recibe el destino

Cada evento es una solicitud POST con un cuerpo JSON. Ejemplo de un aviso al equipo pedido por un empleado de IA:

{
  "schema_version": "business-webhook.v1",
  "id": "5b0c5e2e-0000-4000-8000-000000000001",
  "type": "conversation.handoff_requested",
  "occurred_at": "2026-10-07T09:30:00.000Z",
  "business": { "name": "Example Studio" },
  "actor": { "kind": "ai_employee" },
  "channel": "telegram",
  "employee": { "name": "Anna" },
  "conversation": { "url": "https://app.example.com/businesses/studio/inbox?conversation=example" },
  "customer": { "name": "Maria", "email": "maria@example.com", "phone": "+1 555 0100" },
  "booking": null,
  "handoff": { "reason": "ai_request", "reason_text": "The customer wants to discuss a discount" },
  "support_case": null
}

Las secciones que no corresponden al evento son null. El evento de «Enviar prueba» tiene el tipo webhook.test y todas las secciones salvo business son null. Los datos no llevan texto traducido: los nombres son tal como se guardaron, los códigos son palabras fijas en inglés y las horas están en UTC.

"message": {
  "id": "6c1d0f52-0000-4000-8000-000000000002",
  "sequence": 12,
  "author": "customer",
  "text": "Hello, can I book for Friday?",
  "created_at": "2026-10-07T09:29:41.000Z",
  "attachments": [{ "kind": "image", "name": "photo.jpg", "media_type": "image/jpeg" }]
}

Los mensajes y las transcripciones pueden llegar desordenados y repetirse, así que no dependa del orden de llegada. Use sequence para restaurar el orden de los mensajes de una conversación y descarte la entrega cuyo webhook-id ya haya procesado. La transcripción repite mensajes que quizá ya recibió uno a uno: úsela para comprobar o reconstruir toda la conversación.

Cómo comprobar la firma

Cada petición lleva tres cabeceras del estándar Standard Webhooks: webhook-id, webhook-timestamp y webhook-signature. Zapier y Make no las comprueban. En tu propio servidor usa la biblioteca oficial de Standard Webhooks para tu lenguaje: pásale el secreto tal como se muestra (empieza por whsec_), el cuerpo original sin modificar y las tres cabeceras. Comprobación manual:

signed_content = webhook-id + "." + webhook-timestamp + "." + raw request body
signature      = "v1," + base64( HMAC-SHA256( key, signed_content ) )
key            = base64-decoded part of the secret after "whsec_"

La cabecera webhook-signature contiene v1, y la firma. Después de «Cambiar el secreto» contiene dos firmas separadas por un espacio: acepta la petición si coincide cualquiera. Rechaza las peticiones cuya marca de tiempo difiera de tu reloj en más de cinco minutos.

Reintentos y desactivación automática

El destino debe responder con un código 2xx en 10 segundos. No se siguen las redirecciones: una dirección que redirige cuenta como error. Si no, ReceptionWorks lo intenta de nuevo: enseguida y después a 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas y 12 horas. Son 7 intentos en unas 21 horas. Si todos fallan, el envío queda como No entregado en «Registro de envíos» y puedes hacer clic en «Enviar de nuevo». Los reintentos llevan el mismo webhook-id, así que el destino puede descartar duplicados.

Un destino se desactiva automáticamente si responde que la dirección ya no existe (código 410) o si cinco eventos seguidos no se entregan. La ficha muestra entonces «Desactivado automáticamente» con el motivo y tu equipo recibe una notificación. Corrige la dirección y haz clic en «Activar»: los eventos perdidos mientras tanto no se envían.

Pausa, secreto nuevo y eliminación

Conviene saber

Qué sigue

← Todos los artículos