Construir
ES
Unipile MCP · Webhooks

Conecte webhooks de LinkedIn, WhatsApp y email con un agente de código

LinkedIn no ofrece un webhook público para los mensajes de un miembro. Unipile los envía a su endpoint y, con el Servidor MCP de Unipile , su agente escribe el handler.
Conecte webhooks con un agente Documentación de webhooks
Prueba gratis de 7 días, sin tarjeta.
Su agente · crm-app
Unipile MCP conectado
Sarah
Suscríbete a los webhooks de mensajes nuevos y actualiza la cronología del contacto.
Ejecutar peticiónPOST /v2/webhooks/endpoints/201 · we_…
Se han creado el endpoint en la app de Development y un handler idempotente con cola.
3 archivos modificados · primer evento recibido en menos de un segundo
Describa la próxima función…
El objetivo

Lo que quiere conseguir

Mostrar un mensaje o un email nuevo en su producto en cuanto llega, y reaccionar cuando una cuenta se desconecta, sin polling. LinkedIn no tiene ningún webhook público de mensajes para una cuenta de miembro; Unipile envía el mismo evento en todos los canales.
LinkedInNuevo mensaje de LinkedInen la cuenta que conectó su usuario
WhatsAppNuevo mensaje de WhatsAppmismo evento, otro canal
GmailNuevo emailGmail, Outlook o IMAP
message.newmessage.newemail.new
Su app · timeline del contactoPOST /webhooks/unipile
LinkedInSarah K. ha respondido en LinkedIn0,4 s
WhatsAppTom R. ha enviado un mensaje de WhatsApp0,3 s
GmailAna L. ha enviado la propuesta por email0,5 s
Encolado, deduplicado, escrito una sola vez
Sin ello Bucles de polling y puntos ciegos
Un job que sondea cada cuenta cada treinta segundos, casi siempre para nada.
Ningún evento de mensaje de LinkedIn, porque la plataforma no expone ninguno para una cuenta de miembro.
Una cuenta desconectada que descubre el usuario, no su producto.
Con el servidor MCP de Unipile El resultado en su aplicación
Un endpoint de webhook suscrito a los eventos que gestiona, creado en su aplicación de Development.
Un handler que responde de inmediato, procesa desde una cola y escribe cada evento una sola vez.
Una timeline de contacto y un estado de cuenta que se actualizan en menos de un segundo, probados antes de publicar.
Prompt, pasos, código

Dé el prompt a su agente

Dos prompts, cada uno con los endpoints de Unipile que el agente lee y ejecuta y lo que llega a su proyecto. Las rutas están completas, sobre la URL base de la API https://api.unipile.com, con su clave con scope en la cabecera X-API-KEY .
Su agente · crm-appApp de Development
Suscríbete a los webhooks de mensajes nuevos de Unipile y actualiza la cronología del contacto: crea el endpoint de webhook para message.new y email.new, añade un handler idempotente en esta aplicación y pon el procesamiento en cola.
Leer endpointPOST /v2/webhooks/endpoints/esquema cargado
Ejecutar peticiónPOST /v2/webhooks/endpoints/201 · we_… + secret
Se ha creado el endpoint con trigger_events: ["message.new", "email.new"] y la URL pública de la app, se ha guardado el secret devuelto en el servidor y se ha añadido POST /webhooks/unipile que valida la entrega, responde 200 de inmediato y encola el payload, y un worker que deduplica por el ID del objeto antes de escribir en la cronología del contacto. Mensaje de prueba enviado en la app de Development: cronología actualizada.3 archivos modificados · con cola, idempotente, verificado

Confirmar primero, procesar después, escribir una sola vez

El agente lee el contrato del endpoint a través del servidor: trigger_events y url son obligatorios, account_ids acota el alcance y la respuesta incluye el ID del endpoint y su secret. Después escribe el handler como lo necesita un webhook: 2xx inmediato, procesamiento asíncrono, deduplicación por el identificador del objeto y revisión del registro de entregas cuando parece faltar algo.
Endpoints que usa el agente
POST/v2/webhooks/endpoints/GET/v2/webhooks/endpoints/GET/v2/webhooks/conversations/GET/v2/{account_id}/chats/{chat_id}/messages/{message_id}
Error frecuente: Hacer el trabajo dentro del handler. Responda 2xx de inmediato y procese el evento desde una cola, o las entregas expirarán y se reintentarán.
Alimentar una bandeja unificada con estos eventos
Su agente · crm-appApp de Development
Gestiona los webhooks del ciclo de vida de la cuenta: con account.status.disconnected marca la cuenta como pendiente de atención y muestra un botón Reconectar, y con account.add guarda el nuevo account_id en el workspace indicado en state.
Leer endpointPOST /v2/webhooks/endpoints/enum de eventos
Ejecutar peticiónPATCH /v2/webhooks/endpoints/{id}200 · eventos actualizados
Se han añadido account.add, account.reconnect y account.status.disconnected al endpoint. Con account.add , el worker guarda el account_id en el workspace indicado en state; con account.status.disconnected , marca la cuenta y la página de Ajustes muestra el botón Reconectar, que llama a la ruta de reconexión de Hosted Auth. Verificado desconectando la cuenta mock en la app de Development.2 archivos modificados · reconexión visible en la interfaz

Los eventos de cuenta cierran el ciclo con Hosted Auth

account.add y account.reconnect llevan el state que usted definió al crear el enlace de autenticación, lo que convierte el webhook en la fuente de verdad de una nueva conexión. Los eventos de estado avisan a su producto de que una cuenta requiere atención antes de que el usuario lo note. El agente conecta ambos al mismo endpoint y mantiene el handler idempotente.
Endpoints que usa el agente
PATCH/v2/webhooks/endpoints/{id}GET/v2/accounts/{account_id}POST/v2/auth/link
Error frecuente: Suscribirse a todo. Existen treinta y nueve eventos; un endpoint suscrito a todos recibe confirmaciones de lectura y aperturas de seguimiento sin parar. Suscríbase a lo que gestiona.
Implementar el flujo de reconexión con un agente
Payload

El body del endpoint, la respuesta y los eventos

Literal del contrato v2 que el agente lee a través del servidor. Dos campos son obligatorios, la respuesta lleva el secreto y los eventos se agrupan por familias.
1Cree el endpointtrigger_events y url son obligatorios. account_ids limita el endpoint a algunas cuentas; vacío u omitido, escucha todas las cuentas de la aplicación.POST https://api.unipile.com/v2/webhooks/endpoints/ { "trigger_events": ["message.new", "email.new", "account.add"], "url": "https://app.example.com/webhooks/unipile", "account_ids": ["acc_…"], "description": "crm timeline" }
2La respuestaUn WebhookEndpoint con su id, la aplicación, el secreto que debe guardar en el servidor y las cuentas a las que apunta.{ "object": "WebhookEndpoint", "id": "we_…", "application_id": "app_…", "enabled": true, "secret": "…", "trigger_events": [ … ], "account_targets": [ … ] }
3Los eventos, por familiaCuenta (status, add, reconnect, remove, sync), mensaje (new, update, delete, confirmaciones, reacciones), chat, email (new, bounce, delete, borradores, carpetas), calendario (create, update, delete, event.*), tracking y relaciones.message.new · message.update · message.receipt.read · chat.update email.new · email.new.bounce · email.draft.new · email.folder.update account.add · account.reconnect · account.status.disconnected · account.initial_sync.completed
De Development a producción

Pruebe primero en una aplicación de Development

Su dashboard de Unipile separa la aplicación de Development de la de Production. Dé al agente una clave con scope de Development, una cuenta de prueba y una URL de túnel: eventos reales, sin ningún cliente real.
1Cree el endpoint en la app de DevelopmentURL de túnel, trigger_events limitado a lo que gestiona.
2Reciba un evento de extremo a extremoaccount.add desde un enlace Hosted Auth mock, luego message.new desde la cuenta de prueba.
3Repítalo y cambie luego de claveEl worker escribe una sola vez; account_ids restringido al cliente correcto antes de Production.
crm-app · DevelopmentUsada por su agente
Scopedev-tests · 2 cuentas
Clavescoped Account API key
CuentasCuenta de prueba LinkedIn, buzón de prueba Gmail
Webhooks1 endpoint · eventos de mensaje
crm-app · ProductionSin tocar
Scopeuno por workspace
Clavescoped keys, in your backend only
Cuentaslas cuentas propias de sus usuarios, vía Hosted Auth
Resolución de problemas

Errores habituales y qué significan

Los cuatro fallos que vuelven poco fiables los webhooks, y cómo se corrige cada uno. Ninguno tiene que ver con los eventos en sí.
El endpoint responde con lentitud
Las entregas caducan y se acumulan como reintentos. SoluciónResponda 2xx de inmediato y procese desde una cola. Un handler que escribe en la base de datos antes de responder acaba reproduciendo su propio atasco.
Un handler que no es idempotente
El mismo mensaje aparece dos veces en la timeline. SoluciónEl mismo evento puede entregarse más de una vez. Deduplique por el identificador de objeto que lleva el payload antes de escribir.
Suscrito a todo
El endpoint recibe confirmaciones de lectura y aperturas de tracking sin parar. Solucióntrigger_events acepta treinta y nueve valores. Suscríbase a los eventos que gestiona, y cree varios endpoints cuando el procesamiento sea distinto.
account_ids olvidado en un producto multicliente
El worker de un cliente recibe los eventos de otro. SoluciónVacío u omitido, account_ids escucha todas las cuentas de la aplicación. Restrínjalo explícitamente por cliente, o filtre por la cuenta del payload antes de escribir.
6000+ Empresas que innovan con Unipile
La confianza de los líderes del sector
1 API
Racionalizar las operaciones de los principales canales de comunicación
2 días
Rápida integración en directo con una configuración mínima
30%
Reducción de los esfuerzos y recursos de mantenimiento

Seguridad y conformidad integradas

Protección de nivel empresarial para sus datos y flujos de trabajo Más información sobre nuestra seguridad
SOC 2 Tipo II
SOC 2 Tipo II
Certificado
Controles de seguridad auditados de forma independiente que garantizan la protección de datos y la integridad operativa.
GDPR
GDPR
Conforme
Pleno cumplimiento de la normativa europea de protección de datos para la privacidad de los usuarios.
99.9%
Tiempo de actividad de la plataforma en los últimos 24 meses
24/7
Asistencia global con API de alto rendimiento

FAQ de webhooks

Si LinkedIn tiene un webhook de mensajes, cómo crear un endpoint, qué eventos existen, cómo limitar un endpoint a un solo cliente y cómo verificar una entrega.
No para una cuenta de miembro. Los webhooks públicos de LinkedIn cubren las acciones sociales de una organización y los formularios de leads; los mensajes de miembro dependen de un programa de compliance que ya no admite nuevos partners. Con Unipile, el evento message.new cubre LinkedIn igual que cualquier otro canal, en la cuenta que su usuario conectó por sí mismo.
POST https://api.unipile.com/v2/webhooks/endpoints/ con la cabecera X-API-KEY y un body que lleva trigger_events y url. La respuesta lleva un id en we_… y un secret.
Treinta y nueve valores repartidos entre las familias account, message, chat, email, calendar, tracking y relation. Los más usados son message.new, email.new, account.add, account.reconnect y account.status.disconnected.
Con account_ids, un array de identificadores en acc_…. Omitido o vacío, el endpoint escucha todas las cuentas de la aplicación.
Al crear el endpoint se devuelve un secret. Guárdelo en el servidor y valide cada entrega antes de procesarla. Su URL debe ser HTTPS y accesible públicamente; el registro de entregas está disponible en la ruta de conversaciones de webhook.