Saltearse al contenido

Nexus Webhook

Nexus Webhook es un componente de inicio: pone en marcha el flujo cada vez que el CRM Nexus avisa de un evento, por ejemplo que entra un contacto nuevo, que una oportunidad cambia de etapa o que se presenta una licitación. Cada evento es una ejecución del flujo.

Nexus firma cada aviso con un secreto. El componente comprueba esa firma, así que el flujo solo se pone en marcha con avisos que vienen de verdad de tu Nexus.

Cuándo usarlo

  • Dar la bienvenida por correo a cada contacto nuevo.
  • Avisar al equipo en Slack o en Teams cuando se gana una oportunidad.
  • Preparar la factura o el alta del cliente cuando una oportunidad llega a su última etapa.
  • Hacer seguimiento de las licitaciones que se presentan y se resuelven.

Configuración

Es Nexus quien llama al flujo. Para que el componente compruebe la firma de cada aviso, crea una credencial Nexus Webhook con el Signing secret que Nexus te da al crear el webhook. Consulta Credenciales.

CampoQué hace
EventsLos eventos que ponen en marcha el flujo. Los demás se ignoran. Por defecto: contact.created, deal.created y deal.stage_changed. Tienen que estar marcados también en el webhook que creas en Nexus.
CredentialOpcional, pero recomendada. La credencial Nexus Webhook con el secreto de la firma (Signing secret, el whsec_… que Nexus muestra una sola vez al crear el webhook). Con ella se rechazan los avisos sin firma o con una firma falsa. Sin credencial, no se comprueba la firma.
Max signature age (s) (avanzado)Rechaza los avisos firmados hace más de estos segundos, para que nadie pueda reenviar uno antiguo. Por defecto, 300. Con 0 no se comprueba.
Skip repeated deliveries (avanzado)Activado por defecto. Nexus puede entregar el mismo evento más de una vez; así cada evento ejecuta el flujo una sola vez.
Run on test pings (avanzado)Desactivado por defecto. El botón Enviar prueba de Nexus envía un aviso de prueba (test.ping): se acepta, pero no ejecuta el flujo salvo que actives esta opción.
DataSirve para probar el componente en el editor: pega aquí un evento de ejemplo y ejecuta el flujo. Cuando el flujo se ejecuta por su webhook, se rellena con lo recibido. Déjalo vacío.

Estos son los eventos:

EventoCuándo llega
contact.createdSe crea un contacto nuevo.
contact.updatedAlguien edita un contacto a mano en Nexus.
deal.createdSe crea una oportunidad.
deal.stage_changedUna oportunidad cambia de etapa, también cuando se gana o se pierde.
deal.wonSe gana una oportunidad.
deal.lostSe pierde una oportunidad.
resource.createdSe publica un recurso de contenido nuevo a través de la API, por ejemplo con Nexus Marketing.
tender.submittedSe presenta una licitación.
tender.resolvedSe resuelve una licitación.

Una oportunidad ganada o perdida envía su deal.won o deal.lost y, además, un deal.stage_changed. No existe un evento para cualquier cambio de una oportunidad: los cambios de importe o de título no avisan.

Configurarlo en Nexus

  1. Despliega una versión del flujo: las llamadas al webhook ejecutan la versión desplegada. Ver Versiones y publicación.
  2. Abre la ventana Acceso a API, ve a la pestaña Webhook, elige la Clave API y copia la dirección. Tiene esta forma: <dirección de la API de NappAI>/api/v1/webhook/<id del flujo>?x-api-key=<clave API>. La clave va dentro de la dirección porque Nexus no puede añadir cabeceras a sus avisos. Ver Claves API.
  3. En Nexus, un administrador (rol ADMIN) va a Administración › Integraciones y crea un webhook de salida (Nuevo webhook): pega la dirección del flujo en URL del webhook, marca en Avisar cuando los mismos eventos que en Events y pulsa Crear webhook.
  4. Nexus muestra el Secreto de la firma, que empieza por whsec_. Cópialo enseguida, porque Nexus no lo vuelve a mostrar: crea una credencial Nexus Webhook, pégalo en su campo Signing secret y elige esa credencial en el campo Credential del componente.
  5. Despliega de nuevo el flujo y pulsa Enviar prueba en Nexus para comprobar que el aviso llega.

Resultado

La salida Data entrega el evento con estos datos:

  • event: el evento, por ejemplo deal.stage_changed.
  • event_id y delivery_id: el identificador del evento y el de esta entrega.
  • occurred_at: cuándo ocurrió.
  • contact, deal, previous_stage, resource y tender: los datos completos del contacto, la oportunidad, la etapa anterior, el recurso o la licitación, según el evento.
  • Atajos para lo más usado: contact_id, contact_name, contact_email, contact_company, deal_id, deal_title, deal_amount, deal_status, stage_name y url (el enlace al elemento en Nexus).

Si llega un evento que no está marcado en Events, un aviso de prueba o una entrega repetida, el flujo se detiene en este componente sin dar error. Si la firma no es válida o es demasiado antigua, el aviso se rechaza.

Ejemplo

Una empresa de software quiere que cada cliente nuevo empiece su formación en cuanto se cierra la venta.

  1. Añade Nexus Webhook, marca deal.stage_changed en Events y elige la credencial Nexus Webhook con el secreto de tu webhook de Nexus.
  2. Conecta Data a un Data Conditional Router con deal_status en Key Name, equals y WON en Compare Value.
  3. Conecta su salida True Output a AcademIA Enrollment con la operación Invite to Path, la ruta de bienvenida en Path ID y el dato contact_email en Emails.
  4. Añade un correo de bienvenida al cliente con las instrucciones para entrar en AcademIA.

Buenas prácticas

  • Usa siempre una credencial Nexus Webhook. Sin ella no se comprueba la firma y cualquiera que tenga la dirección del flujo puede ponerlo en marcha.
  • Marca solo los eventos que vayas a usar, y los mismos en Nexus y en Events.
  • contact.updated solo llega cuando alguien edita el contacto a mano en Nexus, no cuando cambia por una importación o una automatización.
  • Un flujo solo puede tener un componente de webhook.

Seguridad y limitaciones

  • Nexus reintenta los avisos que fallan, así que el mismo evento puede llegar más de una vez. Skip repeated deliveries evita que el flujo se ejecute dos veces.
  • Si cambias el secreto en Nexus o creas otro webhook, edita la credencial Nexus Webhook y pon el nuevo whsec_… en Signing secret: con el antiguo, los avisos se rechazan.
  • El aviso lleva los datos básicos del contacto o de la oportunidad. Para leer más, usa Nexus CRM con el identificador que llega en el evento.
  • Al probar pegando un evento en Data no se comprueba la firma: solo se comprueba en las llamadas reales.

Componentes relacionados