Una API permite pedir datos o acciones
Una API define operaciones que otro sistema puede solicitar: consultar un pedido, crear un contacto o actualizar un estado. La solicitud incluye autenticación y datos; la respuesta informa el resultado.
REST y JSON son formas comunes de diseñar e intercambiar esa información, pero una integración también debe respetar permisos, límites de uso y versiones.
Un webhook avisa que algo ocurrió
En lugar de consultar periódicamente si cambió un pago o un pedido, el sistema de origen envía un evento a una URL configurada. Ese aviso reduce espera y consultas innecesarias.
Recibir el evento no significa confiar ciegamente. El endpoint debe validar firma u otro mecanismo, controlar duplicados y responder sin exponer lógica sensible.
El patrón habitual combina ambos
Un proveedor de pagos puede enviar un webhook con un identificador. El receptor valida el aviso y luego consulta la API para obtener el estado completo y vigente antes de actualizar el pedido.
Este diseño separa notificación y verificación. También permite recuperar el proceso si el evento llega tarde, repetido o fuera de orden.
Controles que no deben faltar
La conexión técnica es solo una parte de la integración. Para operar hace falta definir cómo se detecta, registra y recupera un fallo.
- Autenticación y validación de firma cuando el proveedor la ofrece.
- Idempotencia para no procesar dos veces el mismo evento.
- Reintentos con límites y una ruta de revisión.
- Mapeo y validación del contrato de datos.
- Logs sin credenciales ni información sensible innecesaria.
- Alertas para fallos que no pueden recuperarse automáticamente.
Qué llevarse.
- La API sirve para solicitar; el webhook, para notificar.
- Un webhook puede disparar una consulta por API antes de actuar.
- Duplicados y eventos fuera de orden son escenarios normales que deben diseñarse.
- La fuente de verdad y los estados válidos deben acordarse antes de integrar.
Preguntas frecuentes
¿Un webhook reemplaza una API?+
No. El webhook comunica un evento; la API suele ofrecer el detalle y las acciones. Pueden existir por separado, pero normalmente se complementan.
¿Qué pasa si un webhook se envía dos veces?+
El receptor debe reconocer el identificador o una clave idempotente y evitar repetir la acción. Asumir entrega única es riesgoso.
¿Es mejor consultar una API cada cierto tiempo?+
Depende. El polling puede servir si no hay webhooks o si se necesita conciliación periódica, pero genera más consultas y puede introducir demora.