API o webhook: cómo se avisan entre sí tus herramientas
Qué es una API y qué es un webhook, por qué se usan juntos en un pago, cómo elegir entre uno y otro, los cuidados para que no falle y un prompt para que Claude configure tu primer webhook de forma segura.
Descargar el PDF183 KBEn esta página · 7 partes
Cuando conectas tu app con otra herramienta, tarde o temprano aparecen dos palabras: API y webhook. Suenan parecidas y se confunden, pero resuelven problemas opuestos. Una es para preguntar y la otra es para que te avisen.
La analogía del paquete
Compraste algo por internet y esperas el paquete. Hay dos formas de enterarte de que llegó:
- Con una API llamas tú a la tienda y preguntas «¿ya salió mi pedido?». Si no preguntas, no te enteras. Si preguntas diez veces, recibes diez respuestas, casi todas iguales.
- Con un webhook te despreocupas. Cuando el paquete llega, el repartidor toca el timbre. No preguntaste nada, y aun así te avisaron en el momento en que pasó.
En términos técnicos, la API es una puerta a la que tú llamas cuando necesitas algo. El webhook es una dirección de tu app a la que otro sistema llama cuando algo ocurre.
Un ejemplo con pagos
Imagina que vendes algo en tu app y cobras con una plataforma de pagos:
- La persona paga en la página de la plataforma, no en tu app.
- La plataforma te avisa con un webhook: «el pago de este pedido se aprobó».
- Tu app recibe el aviso y activa la compra: da el acceso, manda el correo, anota la venta.
Sin el webhook tendrías que preguntar cada pocos segundos si ya se pagó. Con el webhook, tu app despierta justo cuando hace falta.
Por qué se usan juntas
Un webhook suele ser breve: te dice que pasó algo, no siempre todo lo que necesitas saber. Por eso lo normal es combinarlos:
- El webhook avisa que hay un pago nuevo.
- Tu app usa la API para traer el detalle: quién pagó, qué compró, en qué estado quedó.
Así no dependes solo de lo que venga en el aviso, y puedes confirmar con la fuente que lo que te llegó es real.
Cuál usar
| Si necesitas... | Usa | Por qué |
|---|---|---|
| Enterarte en el momento de que algo ocurrió | Webhook | Te avisan sin que preguntes |
| Consultar o traer información cuando tú quieras | API | Tú decides cuándo y qué pedir |
| Crear, cambiar o borrar algo en otro servicio | API | Es una orden tuya, no un aviso |
| Reaccionar a un pago, una suscripción o un formulario | Ambos | El webhook avisa y la API trae el detalle |
Los cuidados
Un webhook recibe llamadas de afuera, así que hay cuatro cosas que conviene resolver desde el primer día.
- Necesita una dirección pública. El otro sistema tiene que poder llegar a tu app por internet. Mientras pruebas en tu computador, esa dirección no existe: los avisos no llegan a
localhost. Para probar existen túneles, herramientas que te prestan una dirección pública temporal que apunta a tu computador. - Verifica la firma. Cualquiera podría enviar un aviso falso a tu dirección. Los proveedores firman cada aviso con un secreto compartido, y tu app debe comprobar esa firma antes de creerle. Si no coincide, lo descarta.
- Responde rápido con un código 2xx. Cuando recibas el aviso, confirma enseguida con una respuesta de éxito (200, 201, 204) y haz el trabajo pesado después. Si tardas o respondes con error, el proveedor interpreta que falló y vuelve a intentarlo.
- Tolera avisos repetidos. Justamente por esos reintentos, el mismo aviso puede llegar más de una vez. Tu app debe poder procesarlo dos veces sin duplicar nada: no dar el acceso doble ni anotar dos ventas. A esto se le llama idempotencia, y se logra guardando el identificador de cada aviso ya procesado.
Pídele a Claude que lo configure
Si prefieres que Claude te lo arme, copia este prompt:
Quiero recibir webhooks de [nombre del proveedor] en mi app. Crea la ruta que los recibe y hazlo así. Uno, verifica la firma de cada aviso con el secreto guardado en una variable de entorno, nunca en el código, y descarta los que no coincidan; dos, responde con un 2xx de inmediato y procesa el trabajo después; tres, guarda el identificador de cada aviso procesado para que, si llega repetido, no se duplique nada; cuatro, registra en el proveedor la URL final exacta, sin redirecciones; cinco, explícame cómo probarlo en modo de prueba del proveedor, con un túnel si estoy en mi computador, y no lo des por terminado hasta que veas un aviso de prueba procesado una sola vez.
En tres líneas
- La API es para preguntar tú; el webhook es para que te avisen.
- En un pago se usan juntos: el webhook avisa y la API trae el detalle.
- Los cuidados clave son una dirección pública, verificar la firma, responder rápido con 2xx y tolerar avisos repetidos.