Saltar al contenido principal
FlowEstate envía webhooks cuando los leads, proyectos o unidades cambian. Los suscriptores registran una URL destino y un tipo de evento; FlowEstate distribuye requests POST firmados con cuerpo JSON. Para gestionar suscripciones programáticamente (crear, listar, eliminar), ver la Referencia API de webhooks. Esta página cubre lo que tu receptor necesita hacer una vez creada la suscripción.

Headers

Cada entrega incluye:

Body

data depende del evento:
  • Eventos lead.* llevan data.lead.
  • Eventos project.* llevan data.project.
  • Eventos unit.* llevan data.unit y data.project.
  • lead.note_added lleva data.leadId y data.note.
  • lead.communication_logged lleva data.leadId y data.communication.
Para la lista completa de eventos ver Enums.

Verificar la firma

Verifica siempre la firma antes de confiar en un payload. Cualquiera que conozca tu URL puede pegarle; solo FlowEstate tiene el secret.
Firma los bytes crudos del cuerpo. Re-serializar el JSON parseado va a producir una firma diferente porque el orden de las claves, los espacios y el formato de números pueden diferir.
El secret viene en la respuesta de POST /webhooks/subscriptions y se muestra solo una vez. Si lo pierdes, elimina la suscripción y crea una nueva.

Acuse de recibo

Devuelve cualquier status 2xx para acusar recibo. FlowEstate no lee el cuerpo de la respuesta — un 200 vacío está bien. Si tu handler hace trabajo pesado (llama otros APIs, escribe a una BD lenta), acusa primero, procesa después:
El timeout de entrega es de unos pocos segundos — handlers lentos provocan reintentos innecesarios.

Política de reintentos

Las entregas fallidas (error de red, timeout, o HTTP ≥ 400) se reintentan con este backoff: Después de cinco intentos fallidos la entrega se marca como failed y no se reintenta más. El header X-FlowEstate-Delivery se mantiene constante a través de los reintentos — úsalo como tu clave de idempotencia al procesar.

De dónde vienen los eventos de leads

Un lead puede entrar a FlowEstate por varias puertas, y X-FlowEstate-Source te dice por cuál entró:
Espera más tráfico que antes. Hasta esta versión, solo los leads creados por el API REST, el panel y la importación masiva emitían lead.created y lead.assigned. Los leads que llegaban por un webhook entrante, Meta lead ads o WhatsApp eran silenciosos — tu endpoint nunca se enteraba de ellos.Ahora emiten los mismos eventos que cualquier otro canal, etiquetados con X-FlowEstate-Source: system. Si tu organización recibe la mayoría de sus leads por esos canales, tu volumen de entregas va a subir en consecuencia — y en el plan Free puede alcanzar el cupo mensual de más abajo. El payload no cambió en nada; simplemente hay más.
lead.assigned también se dispara cuando se rutea un contacto repetido. Publicar un contacto que ya existe fusiona sobre el lead existente (Deduplicación y fusión), y si ese lead todavía no tenía dueño, el round robin se lo asigna — así que una fusión puede producir un lead.assigned sin un lead.created que lo preceda. Tratá los dos eventos como independientes. Una fusión no emite lead.updated. El enriquecimiento es silencioso hoy en todos los canales.

Cupo mensual de eventos

Las entregas salientes se miden por mes calendario y por organización: Un evento distribuido a tres endpoints cuenta como tres entregas.
Alcanzar el cupo es silencioso. Una vez que la organización pasa su conteo mensual, los eventos siguientes se descartan antes de despacharse: no se intenta ninguna entrega, no se agenda ningún reintento, y tu receptor no tiene forma de distinguir entre “no pasó nada” y “se acabó el cupo”. Los eventos no quedan encolados ni se reproducen cuando empieza el mes siguiente.Si tu integración no puede perder eventos, mantené la organización en un plan sin cupo, o reconciliá periódicamente contra GET /leads en vez de confiar solo en el stream.

Prevención de bucles

Cuando escribes a FlowEstate vía este API REST, el webhook resultante se distribuye con X-FlowEstate-Source: api. Si tu receptor también escribe de vuelta a FlowEstate, descarta los eventos con source api para evitar un bucle infinito.
Los demás valores de source:
  • ui — cambio hecho por un usuario en el panel de FlowEstate, incluida la importación masiva.
  • system — cambio hecho sin una persona de por medio: un lead que llega por un webhook entrante, Meta lead ads o WhatsApp, más los workers internos como asignaciones y automatizaciones.
  • api — cambio hecho a través de este API REST (tus propias escrituras, plataformas partner).
Filtrá solo por api. Descartar también system te haría tirar justamente los leads entrantes a los que más te conviene reaccionar.