Las claves verificadas
- Un webhook entrega datos automáticamente a una URL cuando ocurre un evento suscripto. Ver evidencia
- Consultar una API periódicamente requiere que la aplicación pregunte si hay datos nuevos. Ver evidencia
- Stripe exige verificar la firma sobre el cuerpo original y recomienda responder 2xx antes del trabajo complejo. Ver evidencia
- GitLab recomienda receptores rápidos y preparados para posibles eventos duplicados. Ver evidencia
Qué es un webhook y cómo entrega un evento
Un webhook es un mecanismo para que un sistema avise a otro cuando ocurre un evento. Al configurarlo se registra una URL y se eligen los eventos de interés. Cuando sucede uno, el emisor envía una solicitud HTTP con datos a esa dirección para que la aplicación receptora actúe.
También puede servirte: Qué es una API y cómo conecta dos aplicaciones
GitHub, por ejemplo, permite recibir entregas cuando se abre una solicitud de cambios o se envía código. Stripe usa endpoints HTTPS para eventos asíncronos como la confirmación de un pago. El contenido y los encabezados varían según el proveedor: JSON es habitual, pero no define por sí solo a un webhook.
Webhook o consulta periódica a una API
La diferencia práctica está en quién inicia el intercambio. Con una consulta periódica, la aplicación pregunta a una API cada cierto tiempo si apareció información nueva. Con un webhook, el servicio emisor inicia la entrega cuando detecta el evento. Así puede reducir consultas innecesarias y acercar la actualización al momento en que ocurre.
Una API sigue siendo útil para pedir información bajo demanda, recuperar el estado actual o ejecutar una acción. Un webhook no suele reemplazarla: notifica que algo cambió y la aplicación puede usar la API después para ampliar o confirmar datos. Además, el receptor debe estar disponible en una URL accesible para recibir la entrega.
La cadena segura para recibir un webhook
La secuencia recomendable es recibir el cuerpo sin modificar, comprobar la firma con el secreto del proveedor, validar el tipo de evento y registrar un identificador antes de procesarlo. Stripe advierte que la verificación necesita el cuerpo original de la solicitud y recomienda responder con un código 2xx antes de ejecutar tareas complejas.
Después de validar, conviene enviar el trabajo a una cola y usar el identificador del evento para ignorar repeticiones. GitLab recomienda receptores rápidos, contempla eventos duplicados y reenvíos con la misma clave de idempotencia. La regla concreta depende del proveedor: hay que leer su documentación sobre firmas, reintentos, orden y tiempos límite.
Qué aporta VisteEsto: Nuestro trabajo en esta nota
VisteEsto combina tres documentaciones oficiales en una comparación operativa y una cadena visual de recepción segura.
Fuentes, actualizaciones y metodología 3 fuentes
Fuentes consultadas
- Fuente primariaGitHub Docs: About webhooks
- Fuente primariaStripe Docs: Receive events in a webhook endpoint
- Fuente primariaGitLab Docs: Webhooks
Historial de actualización
- Publicación inicial basada en las documentaciones oficiales de GitHub, Stripe y GitLab.
Cómo elaboramos esta nota
Definimos la consulta principal “qué es un webhook y en qué se diferencia de una API”, contrastamos los datos con 3 fuentes —3 primarias— y revisamos contexto, imágenes y posibles vacíos antes de publicar. Conocé nuestra política editorial y de verificación.
