Webhooks en outbound B2B: cómo evitar emails duplicados y estados imposibles

Un webhook es una notificación HTTP sobre un evento: reply recibido, lead actualizado, email rebotado, reunión creada o stage modificado. El proveedor envía el aviso; tu endpoint decide qué hacer. La trampa aparece cuando el sistema interpreta cada recepción como una orden nueva e irreversible.

Los proveedores pueden reintentar si no reciben una respuesta válida o si hay un timeout. Stripe, cuya documentación ofrece un patrón técnico ampliamente aplicable, advierte que un endpoint puede recibir el mismo evento más de una vez y recomienda registrar IDs procesados. También señala que el orden de entrega no está garantizado. No es una peculiaridad de pagos; es una propiedad que cualquier integración por webhooks debe asumir y confirmar en la documentación de su proveedor.

En outbound, un duplicado puede enviar dos follow-ups, crear dos contactos, sumar dos veces una respuesta o disparar dos tareas para ventas. El error suele parecer pequeño en el log y muy personal en el inbox del prospecto.

Una operación es idempotente cuando procesar el mismo evento otra vez deja el sistema en el mismo estado correcto. No significa ignorar todos los eventos parecidos. Significa reconocer la identidad exacta de la acción y evitar que una redelivery repita su efecto.

Guarda provider, event_id, event_type, object_id, received_at, payload_hash, status y processed_at en una tabla con restricción única sobre provider + event_id. Primero intenta registrar el evento. Si ya existe como completado, responde éxito sin volver a ejecutar. Si existe como fallido o pendiente, aplica una política explícita de reanudación.

Cuando el proveedor no entregue un event_id estable, construye una clave con los campos documentados que definen unicidad: tipo de evento, objeto, versión y timestamp o message_id. Evita usar solo el email del contacto; la misma persona puede responder, rebotar o cambiar de etapa legítimamente en momentos distintos.

El endpoint público debe hacer poco: leer el cuerpo sin alterarlo cuando la verificación lo requiera, validar firma y timestamp, rechazar lo inválido, persistir el evento y devolver una respuesta rápida. La lógica pesada —consultar proveedores, clasificar replies, escribir al CRM o programar otro toque— debe ejecutarse desde una cola o worker.

Separar recepción de procesamiento reduce timeouts y reintentos innecesarios. También permite aplicar concurrencia, prioridad y pausas sin perder eventos. Una respuesta HTTP 200 solo confirma recepción; no debería fingir que cinco sistemas externos ya terminaron su parte.

Define estados received, processing, completed, retryable_failed y dead_letter. Guarda attempt_count, last_error y next_attempt_at. Esa estructura parece menos emocionante que un diagrama con flechas luminosas, pero explica exactamente dónde quedó cada reply cuando una API estuvo caída.

Usa el mecanismo oficial del proveedor: secreto compartido, HMAC, headers firmados y validación de timestamp cuando exista. Compara firmas en tiempo constante y rechaza eventos demasiado antiguos para reducir replay. Mantén secretos por entorno y endpoint; rota sin dejar una ventana ciega.

La verificación suele calcularse sobre el cuerpo original. Parsear JSON, reordenar campos o normalizar espacios antes de validar puede cambiar los bytes y producir una firma distinta. Conserva raw body hasta terminar la comprobación y sigue el algoritmo exacto del proveedor, no uno parecido encontrado en otro SDK.

TLS protege el tránsito, pero no prueba por sí solo quién originó el POST. Una URL difícil de adivinar tampoco es autenticación. Permitir cualquier payload en un endpoint que puede pausar campañas, marcar bajas o crear tareas convierte una integración útil en una API pública accidental.

Supón que campaign.replied llega antes que email.delivered, o que contact.updated con una versión antigua aparece después de una nueva. Si cada evento sobrescribe el registro sin criterio, el CRM puede retroceder. Usa event_time y, cuando el proveedor lo ofrezca, versión o sequence number. Define transiciones válidas en vez de aceptar cualquier estado.

Para eventos comerciales, el significado pesa más que la hora de llegada. Una solicitud de baja debe dominar sobre un follow-up programado. Un reply humano debe detener la secuencia aunque un evento de entrega atrasado aparezca después. Una oportunidad creada no debería reabrirse como lead nuevo porque llegó una sincronización vieja.

Cuando no puedas determinar el orden, consulta la fuente de verdad antes de actuar. Recuperar el estado actual de la campaña o contacto cuesta una llamada API, pero puede evitar una acción irreversible. Registra la discrepancia para saber si el problema es ocasional o una falla de diseño.

Reintenta solo errores transitorios: timeout, conexión, 429 o ciertos 5xx. Usa exponential backoff con jitter y respeta Retry-After cuando exista. Errores de autenticación, payload inválido, objeto inexistente confirmado o transición prohibida necesitan corrección o revisión; repetirlos cada minuto solo convierte una falla clara en ruido caro.

Pon un máximo de intentos y mueve el evento a una dead-letter queue con error, payload, fechas y owner. La cola muerta no es un cementerio decorativo. Necesita alerta, procedimiento de replay y criterio para decidir si la acción todavía es válida. Un follow-up de hace tres semanas quizá ya no deba salir aunque la API haya vuelto.

Aplica un circuit breaker cuando una dependencia falla de forma sostenida. Pausa llamadas nuevas, conserva eventos y prueba recuperación controlada. Si HubSpot está rechazando escrituras, enviar más campañas mientras se acumulan replies sin registrar agranda la inconsistencia justo donde el equipo necesita contexto.

Instantly o Smartlead notifica un reply. El receptor valida firma, registra event_id y confirma. El worker consulta message_id, contacto y campaña; verifica que el reply no esté procesado; clasifica con evidencia; detiene la secuencia; crea o actualiza una actividad en el CRM con una clave externa única; y asigna owner.

Si el webhook se repite, la restricción de event_id evita reclasificar. Si la escritura al CRM respondió con timeout después de completarse, el worker consulta por la clave externa antes de crear otra actividad. Si el clasificador falla, el evento queda reintentable y la secuencia permanece pausada por una regla determinista de seguridad.

La invitación de calendario no se dispara automáticamente solo porque el texto parezca positivo. Primero se verifica intención y contexto. Si el contacto pide información o refiere a otra persona, la siguiente acción cambia. Idempotencia evita duplicados; una taxonomía correcta evita automatizar la respuesta equivocada una sola vez, que también cuenta.

Los webhooks reducen latencia, pero no garantizan consistencia eterna. Ejecuta una reconciliación programada: compara campañas activas, replies, bajas, rebotes, reuniones y oportunidades contra la tabla central. Busca eventos faltantes, objetos duplicados, estados imposibles y contactos activos que deberían estar suprimidos.

Mantén IDs externos: clay_record_id, sending_platform_contact_id, campaign_id, message_id, crm_contact_id y crm_activity_id. Evita usar email como única llave porque cambia, se comparte y puede aparecer con diferencias de mayúsculas o alias. Conserva account_id y contact_id internos como referencias estables.

La reconciliación no debe enviar acciones por defecto. Primero corrige estado y genera una cola de diferencias. Para bajas y bloqueos, aplica la política más segura inmediatamente. Para mensajes o tareas atrasadas, exige vigencia y revisión antes de reproducirlos.

Mide eventos recibidos, duplicados detectados, firma inválida, latencia hasta completado, tasa de éxito al primer intento, reintentos, dead letters y edad de la cola. Separa por proveedor, event_type y versión del workflow. Un promedio global puede ocultar que solo los opt-outs están fallando, precisamente el evento que menos conviene perder.

Añade métricas de consecuencia: secuencias detenidas a tiempo, duplicados evitados, actividades duplicadas en CRM, replies sin owner y discrepancias encontradas en reconciliación. La confiabilidad técnica importa porque protege una decisión comercial concreta.

Define SLO internos, no benchmarks inventados. El tiempo tolerable para sincronizar una apertura secundaria no es el mismo que para aplicar una baja o enrutar una respuesta positiva. Prioriza por impacto y revisa los objetivos con datos del propio sistema.

picos.Ai conecta enriquecimiento, secuencias, respuestas y CRM con una capa de eventos auditable. Diseñamos claves de idempotencia, verificación de firmas, colas, reintentos, estados, dead letters y reconciliación sin convertir cada herramienta en una fuente de verdad distinta.

Podemos empezar por un mapa de eventos de una campaña real: qué los produce, qué acción disparan, qué no puede repetirse y qué sistema tiene autoridad. Después probamos duplicados, eventos fuera de orden, timeouts y caídas antes de activar la cohorte.

El objetivo no es que el webhook “funcione” durante una demo. Es que un reply, una baja y una oportunidad sigan siendo exactamente uno cuando la red, el proveedor o el worker dejan de cooperar. Si tu operación ya usa Clay, Instantly, Smartlead o HubSpot, podemos revisar esa ruta de extremo a extremo.