Guia de la API para desarrolladores: webhooks y eventos explicados

Si vas a construir sobre una plataforma de mensajeria, tarde o temprano chocas con dos conceptos: la API REST (tu codigo llama a la plataforma) y los webhooks (la plataforma llama a tu codigo). Esta guia de la API de mensajeria para desarrolladores explica como encajan, que eventos importan y como implementar un receptor de webhooks robusto que no pierda mensajes.

API REST vs webhooks: la direccion importa

La diferencia fundamental es quien inicia la comunicacion:

• API REST (pull / push saliente): tu aplicacion hace una peticion HTTP para hacer algo: enviar un mensaje, crear un contacto, mover un deal, listar conversaciones. Tu tienes el control del cuando.
• Webhooks (push entrante): la plataforma te envia una peticion HTTP POST cuando sucede algo: llega un mensaje, cambia el estado de entrega, se cierra una conversacion. No preguntas; te avisan.

Usar polling (consultar la API cada X segundos por novedades) es ineficiente y lento. Los webhooks son la forma correcta de reaccionar en tiempo real.

Anatomia de un webhook

Un evento de webhook tipico llega como un POST con un cuerpo JSON. Su estructura suele incluir:

• Un event o type que identifica que paso (por ejemplo message.received, message.status, conversation.closed).
• Un timestamp del momento del evento.
• Un objeto data con la carga util: el mensaje, el contacto, el canal, los metadatos.
• Una firma en las cabeceras (HMAC) para verificar autenticidad.

Tu endpoint debe responder rapido con un 200 OK. Si tardas o devuelves error, la plataforma reintentara, y ahi empiezan los problemas si no diseñaste bien.

Eventos que casi siempre querras escuchar

Aunque cada plataforma tiene su catalogo, estos son los eventos base de cualquier integracion conversacional seria:

1. message.received — entro un mensaje de un cliente.
2. message.sent / message.status — tu mensaje se envio, entrego, leyo o fallo.
3. conversation.created — arranco un hilo nuevo.
4. conversation.assigned — se asigno a un agente o equipo.
5. conversation.closed — se cerro la conversacion.
6. contact.created / contact.updated — cambios en la ficha del cliente.
7. deal.stage_changed / deal.won — movimientos en el pipeline de ventas.

Omnifox, por ejemplo, expone mas de 40 tipos de eventos entre mensajeria, CRM, workflows y llamadas, de modo que puedes suscribirte solo a lo que tu integracion necesita en lugar de recibir todo.

Como construir un receptor robusto

Estas practicas separan una integracion de juguete de una de produccion:

• Verifica la firma siempre. Calcula el HMAC del cuerpo con tu secreto y comparalo con la cabecera. Rechaza cualquier POST que no coincida; es tu unica defensa contra webhooks falsos.
• Responde rapido, procesa despues. Devuelve 200 de inmediato y encola el trabajo pesado. Si procesas de forma sincrona y tardas, provocaras reintentos y duplicados.
• Se idempotente. Los webhooks pueden llegar mas de una vez. Guarda el ID del evento y descarta los repetidos para no crear el mismo registro dos veces.
• Maneja el orden. Los eventos no siempre llegan en orden. Usa el timestamp del evento, no la hora de recepcion, para reconstruir la secuencia real.
• Registra y monitorea. Loguea cada webhook recibido con su ID y resultado. Cuando algo falle, querras poder reproducirlo.
• Ten un endpoint de reintento tolerante. Devuelve 5xx solo si de verdad quieres que reintenten; devolver 4xx suele marcar el evento como fallido definitivo.

Reintentos y colas: el detalle que rompe integraciones

La mayoria de plataformas reintentan un webhook fallido con backoff exponencial durante horas. Esto es bueno (no pierdes eventos) pero peligroso si tu logica no es idempotente: cada reintento puede duplicar un contacto o disparar dos veces una automatizacion. La solucion es siempre la misma: recibe -> valida firma -> responde 200 -> encola -> procesa con deduplicacion por ID. Con ese patron, ni un pico de trafico ni una caida momentanea de tu servidor te haran perder o duplicar datos.

Conclusion

Dominar los webhooks y la API REST es lo que te permite construir experiencias de mensajeria reactivas y confiables: reaccionas en tiempo real, mantienes tus sistemas sincronizados y no pierdes eventos. Verifica firmas, se idempotente, responde rapido y encola el trabajo pesado; con eso cubres el 90% de los problemas de produccion. Si buscas una API limpia con eventos granulares y webhooks bien documentados para empezar hoy, explora Omnifox y conecta tu producto a la conversacion.