Webhooks de eventos

Con los webhooks de eventos tus propios sistemas se enteran al momento de lo que pasa en tu cuenta, para todos los asistentes a la vez. No tienes que añadir una acción a cada asistente. Los webhooks de eventos forman parte de Enterprise; en otros planes la tarjeta explica cómo cambiar de plan.

Evento	Cuándo
conversation.ended	Una conversación (llamada, SMS, WhatsApp o chat web) ha terminado y se conocen el resumen y el resultado.
lead.created	Una conversación trajo una solicitud nueva. Se envía en cuanto se guarda la solicitud, a menudo ya durante la conversación, y una vez por solicitud.
appointment.booked	Se reserva una cita: en el calendario integrado (también cuando se copia a Google Calendar o Microsoft 365) por el asistente o en la página de reservas, o por el asistente en Cal.com o eTermin.
appointment.rescheduled	Se cambia una cita de hora: el asistente, o el cliente en la página de reservas.
appointment.cancelled	Se cancela una cita: el asistente, el cliente en la página de reservas o tu equipo en Citas. Se envía una sola vez: una cita cancelada no se puede volver a cancelar ni mover.

Las conversaciones de prueba del panel nunca envían un evento.

Qué no envía un evento

• Cambios fuera de Yarla. Si cambias o eliminas una cita directamente en Google Calendar, Microsoft 365, Cal.com o eTermin, no nos enteramos y no enviamos nada.
• Una corrección de una solicitud más tarde en la misma conversación, ni un estado nuevo que elija tu equipo. Consulta la solicitud con la API si necesitas lo último; conversation.ended incluye el leadId.
• Completada o no presentado en una cita.

Añadir un webhook

Solo un Administrador gestiona los webhooks de eventos.

1. Abre Ajustes → Conexiones y baja hasta Webhooks de eventos.
2. En Añadir un webhook, escribe la Dirección (https) de tu endpoint.
3. Marca los Eventos que quieras. Por defecto están todos marcados.
4. Elige Añadir webhook.

Puedes tener como máximo 5 webhooks. En Dirección y eventos cambias más tarde la dirección, el nombre o los eventos; el interruptor desactiva un webhook sin eliminarlo. Los cambios se guardan solos.

Añadir o cambiar un webhook solo funciona durante las 2 horas posteriores a iniciar sesión, y solo con tu propio acceso: no mientras un revendedor o nuestro soporte trabaja en tu cuenta. Consulta Cambios que piden volver a iniciar sesión.

La dirección debe ser una dirección https:// completa en internet. Las direcciones locales e internas se rechazan.

Qué enviamos

Cada evento es un POST con Content-Type: application/json:

{
  "id": "evt_01JC4Z0Q8V9T3W6Y2B5N7K1M0P",
  "type": "conversation.ended",
  "createdAt": "2026-11-05T09:14:03.000Z",
  "businessId": "01JB...",
  "data": {
    "conversationId": "voice:...",
    "channel": "voice",
    "direction": "inbound",
    "customerPhone": "+34612345678",
    "customerPhoneVerified": true,
    "customerPhoneVerifiedBy": "caller_id",
    "customerName": "Juan García",
    "outcome": "appointment_booked",
    "summary": "Juan quiere la revisión de su caldera el martes por la mañana.",
    "durationSeconds": 184,
    "leadId": null,
    "appointmentId": "01JC...",
    "variables": {},
    "link": "https://.../inbox/voice:..."
  }
}

• lead.created incluye la solicitud: leadId, customerName, customerPhone, address, problem, urgency, preferredTime, summary y un link.
• appointment.booked, appointment.rescheduled y appointment.cancelled incluyen la cita: appointmentId, serviceName, startAt, endAt, timezone, status, guestName, guestEmail, guestPhone, los fields propios y source. El enlace con el que un cliente cambia la cita nunca va incluido.
• customerPhoneVerified (en conversation.ended y lead.created) y guestPhoneVerified (en las citas) dicen si el cliente demostró ese número en la conversación: true o false. customerPhoneVerifiedBy y guestPhoneVerifiedBy dicen cómo: caller_id (el cliente llamó desde ese número), sms_code, email_code, call_code, whatsapp o phone_change, y null si no se comprobó. Los dos son null si no hay número, o si la cita no se reservó ni se cambió en una conversación. Ver Verificado o no verificado.
• appointment.rescheduled incluye además previousStartAt y previousEndAt: la hora de antes del cambio. El appointmentId no cambia.
• En Cal.com y eTermin, ese servicio guarda la cita: appointmentId es null, provider es calcom o etermin y externalId es su propio identificador. Al cambiar o cancelar una cita de eTermin solo enviamos ese identificador y la nueva hora.
• Las cabeceras X-Yarla-Event (el tipo), X-Yarla-Event-Id (igual que id) y X-Yarla-Delivery (una por envío) distinguen eventos y envíos. Un reenvío mantiene el id del evento, así que puedes ignorar un evento que ya procesaste.

El texto muy largo se acorta para que un envío no pase de 64 KB.

Comprobar la firma

Cada envío lleva una cabecera X-Yarla-Signature, creada con el Secreto de webhook de la misma página, igual que en las acciones HTTP. Lee en Webhooks cómo comprobarla.

Reintentos, prueba y reenvío

• Tu endpoint tiene 5 segundos para responder con un 2xx. Si no responde a tiempo, no hay conexión o responde 408, 429 o un 5xx, lo intentamos de nuevo, hasta tres intentos en total, con una pausa corta entre ellos. Otra respuesta 4xx es definitiva.
• No hay reintentos más tarde. En Últimos envíos ves cada envío de los últimos 30 días con su resultado, y Reenviar manda el mismo contenido otra vez.
• Para Reenviar, guardamos el contenido de cada envío durante 30 días, o menos si guardas las conversaciones menos tiempo. Incluye un número de teléfono, un nombre y un resumen. Si eliminas una conversación o un contacto, ese contenido sigue en el envío hasta que termina ese plazo. Para quitarlo enseguida, elimina el webhook: así también se eliminan todos sus envíos.
• Enviar prueba manda un evento de ejemplo del primer tipo que escucha el webhook, marcado con "test": true, y muestra el resultado al momento.
• Enviar prueba y Reenviar juntos funcionan hasta 20 veces por hora por cuenta.

Después de cambiar a un plan más barato

Los webhooks de eventos forman parte de Enterprise. Si cambias a un plan más barato, o mientras haya un pago de Enterprise pendiente, no se envía nada. Tus webhooks se guardan, inactivos, en Ajustes → Conexiones: vuelven a enviar cuando eliges Enterprise de nuevo (y la factura está pagada), y puedes seguir borrándolos. Consulta Suscripción y facturas.

Artículos relacionados

• Webhooks
• Conexiones
• HubSpot y Pipedrive
• API