Integraciones con webhooks

Los webhooks envían eventos de Deskwoot a una URL que tú eliges, en el momento en que ocurren: una conversación nueva, un mensaje nuevo, una asignación, una conversación resuelta, un cambio en un contacto, una valoración CSAT o un cambio en un ticket. Deskwoot envía cada evento como JSON en una solicitud POST y lo firma, para que tu endpoint pueda comprobar que de verdad viene de Deskwoot. Usa los webhooks para mantener sincronizado un CRM, iniciar tus propias automatizaciones o guardar eventos de soporte en tu propia base de datos, sin tener que preguntarle a la API una y otra vez si hay cambios.

Qué plan necesitas

Los webhooks necesitan el plan Startup o uno superior, y la prueba gratis los incluye. En el plan gratis Hacker, los webhooks que creaste antes siguen en la lista de Configuración > Webhooks y puedes eliminarlos, pero no envían nada hasta que tu plan vuelva a incluir webhooks. Entonces vuelven a enviar solos.

Un webhook solo envía datos hacia fuera de Deskwoot. Para que tu propio servidor o n8n responda a los mensajes de los clientes como un bot, agrega un bot Custom Webhook en Configuración > IA > Más bots, que necesita un plan de pago (Startup o superior). Deskwoot envía cada mensaje del cliente a tu URL y publica la respuesta que devuelve tu servidor, o pasa la conversación a tu equipo. Cada conversación que responde el bot cuenta como 1 conversación de IA. Cuando se acaban tus conversaciones de IA, el bot no responde y la conversación pasa a tu equipo.

Para responder mensajes de clientes, asignar, etiquetar o resolver una conversación o actualizar un contacto desde tu propio código o desde una herramienta como n8n, Make o Zapier, llamas a la API REST de Deskwoot. La API REST necesita un plan Enterprise de pago, y la prueba gratis no incluye acceso a la API. Cada conversación que respondes a través de ella cuenta como 1 conversación de IA. Cómo crear un token: Tokens de API y acceso para desarrolladores.

Crear un webhook

1. Ve a Configuración > Webhooks. Solo los administradores ven esta página.
2. Haz clic en Agregar webhook.
3. En URL del endpoint, escribe la dirección que debe recibir los eventos. Tiene que ser una URL HTTPS pública.
4. En Suscribirse a eventos, marca los eventos que quieres. Si no marcas ninguno, el webhook recibe todos los eventos excepto los de tickets.
5. Haz clic en Crear webhook.

A partir de ahí, Deskwoot envía una solicitud POST con un cuerpo JSON a tu URL cada vez que ocurre un evento que coincide. El interruptor junto a un webhook lo desactiva y lo vuelve a activar, y Editar cambia su URL o sus eventos. La lista muestra cuántos eventos recibe cada webhook, por ejemplo 3 eventos, o Todos los eventos excepto los de tickets cuando no hay ninguno marcado (Todos los eventos mientras los tickets están desactivados).

Eventos de tickets

Mientras los tickets están activados, Suscribirse a eventos también muestra Tickets con Ticket creado, Ticket actualizado, Ticket asignado y Ticket resuelto. Un ticket es trabajo interno de tu equipo, así que nunca envía un evento de conversación. Cada cambio en un ticket envía su evento de ticket en su lugar, y solo a los webhooks que lo marcan. Un webhook sin eventos marcados no recibe eventos de tickets, así que un webhook que creaste antes de los tickets sigue recibiendo solo conversaciones con clientes.

• Un comentario en un ticket es un evento Mensaje creado con conversationKind TICKET. Solo llega a los webhooks que marcan Mensaje creado y al menos un evento de ticket.
• Los datos incluyen ticketId y ticket, el ticket tal como está cuando sale el evento: número, título, estado, prioridad, categoría, equipo, responsable, creador, su propio estado del ticket, etiquetas, atributos personalizados, la conversación de la que salió, y sus tickets colectivos e incidencias de Jira. Ticket actualizado agrega changes y source, Ticket asignado agrega el responsable nuevo y el anterior, y Ticket resuelto agrega quién lo resolvió.
• El texto del resumen del ticket nunca sale. Cuando el resumen cambia, changes.summary es solo true.
• Un ticket colectivo es un ticket con tracker en true y sin contacto. Vincular una conversación o un ticket a un ticket colectivo, o desvincularlo, envía el Ticket actualizado del ticket colectivo con changes.links. Crear, vincular o desvincular una incidencia de Jira, y cada estado nuevo de una, envía Ticket actualizado con changes.linkedIssues.

Consejos

• Suscríbete solo a lo que necesitas. Cada evento es una solicitud a tu endpoint, y menos solicitudes hacen más fácil encontrar errores.
• Responde rápido. Devuelve un estado 2xx en cuanto llegue la solicitud y haz el trabajo pesado en una tarea en segundo plano. Deskwoot espera 10 segundos como máximo.
• Guarda los payloads sin procesar mientras desarrollas, así ves la estructura exacta de cada evento.
• Haz que una segunda entrega no cause problemas. En casos raros un evento llega dos veces, así que procesarlo de nuevo no debe crear duplicados.

Solución de problemas

• ¿No llega ningún evento? Revisa que la URL sea correcta, que se pueda acceder a ella desde internet y que responda con 2xx. Los firewalls o las listas de IP permitidas pueden bloquear las solicitudes sin mostrar ningún error de tu lado. En el plan gratis Hacker, los webhooks no envían nada.
• ¿El cuerpo se ve mal? Léelo como JSON (Content-Type: application/json) y revisa los registros de tu servidor por si hay errores al leerlo.
• ¿Los eventos llegan tarde? Deskwoot envía cada evento enseguida, y un reintento llega 5 segundos después de una entrega fallida. Si los eventos siguen llegando tarde, revisa si tu servidor limita o pone en cola las conexiones entrantes.

Preguntas frecuentes

¿Qué plan necesito para los webhooks?

Startup o superior. Los webhooks necesitan el plan Startup o uno superior, y la prueba gratis los incluye. Un bot Custom Webhook, que responde a tus clientes desde tu propio servidor, necesita un plan de pago (Startup o superior). Para responder a clientes o para asignar, etiquetar o resolver conversaciones desde tu propio código, llamas a la API REST, que necesita un plan Enterprise de pago.

¿Puede un webhook cambiar algo en Deskwoot?

No. Un webhook solo envía eventos hacia fuera. Para responder mensajes de clientes desde tu propio servidor o desde n8n, usa un bot Custom Webhook en Configuración > IA > Más bots, que necesita un plan de pago (Startup o superior). Para responder mensajes de clientes, asignar, etiquetar o resolver una conversación o cambiar un contacto desde tu propio código o desde n8n, Make o Zapier, llama a la API REST, que necesita un plan Enterprise de pago. Cada conversación que respondes de cualquiera de las dos formas cuenta como 1 conversación de IA.

¿A qué eventos me puedo suscribir?

Conversación creada, Conversación actualizada, Conversación asignada, Conversación resuelta, Mensaje creado, Contacto creado, Contacto actualizado y CSAT enviado, y mientras los tickets están activados también Ticket creado, Ticket actualizado, Ticket asignado y Ticket resuelto. Si no marcas ningún evento, el webhook recibe todos los eventos excepto los de tickets. Los datos de cada evento están en la documentación de la API.

¿Por qué mi webhook no recibe eventos de tickets?

Un webhook sin eventos marcados recibe todo excepto los eventos de tickets. Edita el webhook y marca los eventos de tickets que necesitas en Tickets.

¿La entrega va firmada?

Sí. Cada solicitud lleva un encabezado X-Deskwoot-Signature (sha256= seguido del HMAC SHA256 en hexadecimal del cuerpo sin procesar, firmado con el secreto de tu webhook) y un encabezado X-Deskwoot-Event con el nombre del evento. El panel no muestra el secreto; un webhook creado con la API REST lo devuelve una vez en la respuesta. Comprueba la firma antes de procesar una solicitud, para rechazar las solicitudes falsas.

¿Deskwoot vuelve a intentar una entrega fallida?

Una vez. Si la solicitud falla, tu endpoint responde con un error o tarda más de 10 segundos, Deskwoot lo intenta de nuevo después de 5 segundos. Si eso también falla, el evento se descarta, así que prepara tu endpoint para aguantar cortes breves.

¿Qué tan rápido se entregan los webhooks?

Justo cuando ocurre el evento, sin cola. Tu endpoint tiene 10 segundos para responder; una respuesta más lenta cuenta como entrega fallida y recibe el único reintento.

¿Necesito HTTPS?

Sí. Deskwoot solo envía a URL HTTPS públicas y rechaza una URL HTTP cuando guardas el webhook, porque los payloads contienen datos de clientes.

¿Cómo es la solicitud?

Un POST con Content-Type: application/json. El cuerpo es un objeto JSON con event, data (los datos del evento), timestamp y accountId.

¿Puedo recibir el mismo evento dos veces?

Rara vez, por ejemplo cuando tu endpoint procesó la primera solicitud pero respondió demasiado tarde, así que también llegó el reintento. El cuerpo no tiene un ID de evento, así que usa el nombre del evento junto con el ID del objeto en data (por ejemplo, el ID del mensaje) para saltarte los eventos que ya procesaste.

¿Puedo filtrar los eventos antes de que se envíen?

Por tipo de evento, sí: marca solo los eventos que necesitas. Por contenido (por ejemplo, solo las conversaciones de una bandeja de entrada), no. Fíltralos en tu endpoint.

¿Qué pasa si mi endpoint está caído unas horas?

Los eventos de ese tiempo se pierden, porque Deskwoot no guarda nada más allá del único reintento. Cuando tu endpoint vuelva a funcionar, puedes ponerte al día con la API REST (Enterprise): lista las conversaciones ordenadas por la actividad más reciente y compáralas con tus datos.

¿Puedo enviar eventos a varios endpoints?

Sí. Crea un webhook por URL, cada uno con sus propios eventos. Eso ayuda cuando una herramienta necesita todos los eventos y otra solo unos pocos.

¿Cómo pruebo un webhook antes de usarlo en serio?

El panel no tiene un botón de prueba. Apunta un webhook a una URL temporal de un servicio como webhook.site o RequestBin y luego crea un evento real, por ejemplo escribiendo a una de tus bandejas de entrada. Revisa los payloads y tu código que los lee, y luego cambia la URL a tu endpoint real con Editar.