Fundamentos de Webhooks
Los webhooks permiten que los servidores notifiquen a los clientes en tiempo real sobre eventos, sin que el cliente necesite hacer preguntas continuamente.
Descripción compacta
Un webhook es una llamada HTTP que un servidor envía a un endpoint proporcionado por el cliente cuando ocurre un evento específico. Se utilizan para informar sobre pagos, cambios de estado, notificaciones, integraciones y muchos otros eventos. A diferencia del polling, donde el cliente pregunta regularmente si hay algo nuevo, los webhooks permiten que el servidor empuje datos activamente hacia el cliente. Una implementación correcta de webhooks debe considerar seguridad, confiabilidad, idempotencia, estrategias de reintentos y manejo claro de errores. Los webhooks son un patrón fundamental para arquitecturas basadas en eventos e integraciones modernas entre servicios.
Componentes principales
Fuente de eventos y sistema destino
La fuente de eventos es el servidor que dispara el webhook. El sistema destino es el endpoint del cliente que recibe el webhook. Ambos sistemas deben ser capaces de comunicarse por HTTP, y el sistema destino debe ser accesible públicamente si el servidor está fuera de la red propia.
Registrar la URL del webhook
El cliente registra una URL en la fuente de eventos a donde se deben enviar los webhooks. Esta URL generalmente se gestiona a través de un panel de control o una API. Es importante que la URL use HTTPS y se valide para evitar manipulaciones.
Payload y formato de eventos
El payload es el contenido del webhook, generalmente en JSON. Contiene información sobre el evento, como tipo de evento, marca de tiempo, recurso afectado y detalles adicionales. Un campo de ID de evento único ayuda a reconocer duplicados.
Seguridad y firmas
Los webhooks deben firmarse para que el receptor pueda verificar que el mensaje realmente proviene de la fuente esperada. Las firmas HMAC-SHA256 sobre el payload son un procedimiento común. El receptor verifica la firma con un secreto compartido o una clave pública.
Idempotencia en webhooks
Los webhooks pueden enviarse múltiples veces debido a timeouts o reintentos. El receptor debe procesar los eventos de manera idempotente utilizando un ID de evento único. Los eventos con IDs idénticos deben ignorarse o descartarse una vez que ya han sido procesados.
Estrategias de reintentos
Si el receptor no responde con un código de éxito, la fuente de eventos debe reintentar el webhook. Los reintentos deben aplicar backoff exponencial para no sobrecargar el sistema destino. Después de un número determinado de intentos o un período de tiempo específico, la fuente debe abandonar e indicar el evento como fallido.
Códigos de respuesta esperados
El sistema destino debe responder con 2xx cuando recibe exitosamente el webhook. Los códigos 4xx indican que el receptor rechaza o no puede procesar la solicitud. Los códigos 5xx señalan un problema temporal que justifica un reintento. Un código incorrecto puede causar que los eventos se repitan de manera incorrecta o se cancelen erróneamente.
Timeouts
La fuente de eventos debe definir un timeout después del cual considera que la solicitud ha fallado. Los receptores deben confirmar los webhooks rápidamente y realizar procesamientos más largos de forma asincrónica en segundo plano para evitar timeouts.
Registros y monitoreo de webhooks
Ambos lados deben registrar los webhooks, incluyendo ID de evento, marca de tiempo, código de estado HTTP y tiempo de respuesta. El monitoreo ayuda a identificar interrupciones, demoras y frecuencias de errores. Los dashboards de estado de entrega son particularmente útiles.
Pruebas y depuración de webhooks
Para desarrollo, herramientas como ngrok, probadores locales de webhooks o endpoints sandbox son adecuadas. Estas permiten recibir, inspeccionar y depurar webhooks localmente sin necesidad de proporcionar servidores públicos.
Ejemplo práctico
Un servicio de pagos quiere informar a sus clientes cuando un pago fue exitoso. El cliente registra una URL de webhook:
POST /api/v1/webhooks
Content-Type: application/json
Authorization: Bearer token
{
"url": "https://shop.example.com/webhooks/payments",
"events": ["payment.succeeded", "payment.failed"]
}Cuando un pago es exitoso, el servicio de pagos envía un webhook:
POST /webhooks/payments
Content-Type: application/json
X-Event-ID: evt-9876543210abcdef
X-Webhook-Signature: sha256=5d41402abc4b2a76b9719d911017c592
{
"eventType": "payment.succeeded",
"eventId": "evt-9876543210abcdef",
"timestamp": "2026-07-01T12:34:56Z",
"data": {
"paymentId": "pay-123456",
"orderId": "order-7890",
"amount": 79.97,
"currency": "EUR"
}
}El receptor verifica la firma, guarda el ID de evento y procesa el pago. Responde con 200 OK para confirmar la entrega exitosa. Si hay un timeout o un error 5xx, el servicio de pagos reintenta el envío con backoff exponencial.
FAQ: Fundamentos de Webhooks
1. ¿Qué es un webhook?
2. ¿Cuál es la diferencia entre webhooks y polling?
3. ¿Cómo se registra un webhook?
4. ¿Por qué los webhooks deben usar HTTPS?
5. ¿Qué es una firma de webhook?
6. ¿Cómo funciona la idempotencia en webhooks?
7. ¿Qué es backoff exponencial?
8. ¿Qué códigos de respuesta debe devolver un receptor de webhook?
9. ¿Qué sucede si un webhook no puede entregarse?
10. ¿Qué es una Dead Letter Queue en webhooks?
11. ¿El procesamiento de webhooks debe ser sincrónico o asincrónico?
12. ¿Cómo se prueban los webhooks localmente?
13. ¿Qué es un ID de evento?
14. ¿Qué medidas de seguridad son importantes para los webhooks?
15. ¿Qué es un Webhook Replay?
Continúa en la ruta de aprendizaje de APIs
El siguiente artículo en la ruta de aprendizaje de APIs aborda Desarrollo de GraphQL APIs: Esquemas, Resolvers, Subscriptions y Apollo — la alternativa a REST con consultas de datos flexibles y esquema tipado.
Referencias
Libros recomendados para desarrollo de APIs
Si deseas profundizar en webhooks, diseño de APIs y arquitectura de software, te recomendamos los siguientes libros:
Keine Bücher für Kategorie "api-development" gefunden.