{"canonical_url":"https://engineer.company/es/glossary/webhook/","content_markdown":"# webhook\n\n## Qué es\n\nUn webhook es una petición HTTP que un servicio envía a otro en el momento\nen que ocurre algo en su lado: se procesa un pago, se abona una factura o\ntermina una tarea larga. El receptor registra de antemano una URL y el emisor\npublica en ella una descripción de cada evento. La especificación Standard\nWebhooks presenta «webhook» como «un nombre común para las llamadas de retorno\nHTTP» y describe estos mecanismos como un canal por el que un servicio anuncia un evento a otro. A veces el término\nse escribe en dos palabras, web hook, pero Stripe, GitHub y la especificación\nlo escriben en una sola.\n\nLa especificación también describe un webhook como parte de la API de un\nservicio, una especie de API al revés. Normalmente el cliente llama al servicio\ncuando quiere algo. Con un webhook, el servicio llama al cliente cuando tiene\nnovedades. En una integración habitual de API, ambos lados ejecutan servidores\nHTTP: uno para recibir llamadas de API y otro para recibir webhooks. Un servicio\ntambién puede enviar webhooks sin ofrecer su propia API de peticiones. El emisor\nse llama productor, el receptor consumidor, y la URL que registra el receptor\nes su punto de recepción de webhooks.\n\nLa especificación recomienda un POST HTTP con un cuerpo JSON, pero no exige\nun formato ni una estructura concretos para la carga útil. El cuerpo que propone\nincluye un `type`, escrito con puntos y agrupado jerárquicamente, como\n`invoice.paid`; un `timestamp` del momento en que ocurrió el evento, en ISO\n8601; y los datos del evento bajo `data` o en el nivel superior. Puede haber\nmetadatos adicionales en ambos lugares. Los metadatos de entrega van en las\ncabeceras: `webhook-id` identifica el evento, `webhook-timestamp` registra\ncuándo se hizo este intento, en segundos Unix, y `webhook-signature` lo\nautentica. Stripe y GitHub usan sus propios nombres de cabecera, entre ellos\n`Stripe-Signature` y `X-Hub-Signature-256`, y sus reglas de verificación son\ndistintas: Stripe firma una marca temporal del intento junto con el cuerpo,\nmientras que el HMAC de GitHub abarca solo el cuerpo.\n\nLa carga útil puede ser completa e incluir todo el objeto modificado, o\nreducida y llevar poco más que un identificador, dejando que el receptor obtenga\nel resto mediante la API. La especificación sopesa ambas opciones. Una carga\ncompleta ahorra llamadas adicionales a la API. Una reducida supone menos datos\nque generar y enviar, más flexibilidad y más margen para cambios posteriores:\nsiempre puede ampliarse hasta ser completa, pero no al revés. También permite\nauditar el acceso a los datos, porque el receptor debe pedir expresamente lo\nque lee. En cualquier caso, la especificación aconseja cargas pequeñas,\nnormalmente inferiores a 20 kB. Stripe ofrece un formato reducido y lo señala\ncomo el recomendado.\n\n## Por qué importa\n\nSin webhooks, un sistema que necesita conocer un cambio en otro lugar tiene\nque realizar sondeos periódicos: preguntar una y otra vez, casi siempre para oír\nque no ha ocurrido nada, y aun así enterarse del cambio solo en el siguiente\nsondeo. Un webhook invierte el proceso. El servicio que conoce el evento\nllama una vez, cuando ocurre. Así informan los proveedores de pagos, alojamiento\nde código y correo electrónico a los sistemas construidos sobre ellos.\n\nInvertir la dirección tiene costes, y la mayoría recaen en el receptor. Su\npunto de recepción es una URL pública a la que cualquiera en internet puede\nenviar un POST; nada en una petición entrante demuestra quién la envió, de modo\nque la especificación exige verificar su autenticidad en cualquier\nimplementación segura. La entrega se reintenta hasta que el receptor responde\ncon un estado 2xx o la política de entrega deja de intentarlo. Por eso, el mismo\nevento puede llegar más de una vez; Stripe advierte de que los receptores pueden\nrecibir duplicados ocasionalmente. Tampoco se promete el orden: Stripe indica\nexpresamente que no garantiza que los eventos lleguen en el orden en que se\ngeneraron.\n\nEl productor, por su parte, debe seguir intentándolo. La especificación\nrecomienda un calendario de reintentos que abarque varios días, con espera\nexponencial y una pequeña variación aleatoria. Su ejemplo hace diez intentos;\nel último se realiza 75 horas, 35 minutos y 5 segundos después del primero. Stripe\nreintenta durante un máximo de tres días en modo real. Un receptor que vuelve a estar disponible\ndentro de ese plazo recibe automáticamente las entregas pendientes; después, Stripe permite reenviar\nun evento manualmente hasta 15 días después de su creación, o hasta 30 días\nmediante su CLI. Cuando la entrega falla durante mucho tiempo, la especificación\nrecomienda que el productor avise al consumidor por otro canal, como el correo\nelectrónico, y desactive el punto de recepción.\n\n## Cómo se aplica en la práctica\n\nEstas son las cabeceras de una entrega con el formato de la especificación.\nEl identificador, la marca temporal y la firma son los valores de ejemplo que\nusa la propia especificación; el valor de `Host` y la ruta son inventados:\n\n```http\nPOST /webhooks/billing HTTP/1.1\nHost: example.com\nContent-Type: application/json\nwebhook-id: msg_2KWPBgLlAfxdpx2AI54pPJ85f4W\nwebhook-timestamp: 1674087231\nwebhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=\n```\n\nEste es el cuerpo, una carga reducida de la misma especificación, presentada\naquí con sangría para facilitar la lectura. Para transmitirla, la especificación\nrecomienda minificarla:\n\n```json\n{\n  \"type\": \"contact.created\",\n  \"timestamp\": \"2022-11-03T20:26:10.344522Z\",\n  \"data\": {\n    \"id\": \"1f81eb52-5198-4599-803e-771906343485\"\n  }\n}\n```\n\nEl prefijo `v1` indica una firma simétrica: HMAC-SHA256 sobre el identificador\ndel evento, la marca temporal y el cuerpo unidos por puntos, con una clave\nsecreta exclusiva del punto de recepción. Como el identificador y la marca\ntemporal se firman junto con el cuerpo, ninguno puede cambiarse sin invalidar\nla firma. La especificación también permite firmas asimétricas ed25519, marcadas\ncon `v1a`, y las recomienda cuando distintas partes se encargan de proteger al\nproductor y al consumidor.\n\nGitHub también firma sus entregas con HMAC-SHA256, coloca el resumen hexadecimal\nen `X-Hub-Signature-256` con el prefijo `sha256=` y publica un secreto, una\ncarga útil y una firma para probar un verificador. Este verificador en Python\nse ha comprobado con ese ejemplo:\n\n```python\nimport hashlib\nimport hmac\n\n\ndef verify(body: bytes, secret: str, header: str) -\u003e bool:\n    mac = hmac.new(secret.encode(\"utf-8\"), body, hashlib.sha256)\n    expected = \"sha256=\" + mac.hexdigest()\n    return hmac.compare_digest(expected, header)\n\n\nsecret = \"It's a Secret to Everybody\"\nheader = (\n    \"sha256=757107ea0eb2509fc211221cce984b8a\"\n    \"37570b6d7586c22c46f4379c8b043e17\"\n)\nprint(verify(b\"Hello, World!\", secret, header))  # True\nprint(verify(b\"Hello, World! \", secret, header))  # False\n```\n\nBasta un espacio al final del cuerpo para que falle. `hmac.compare_digest`\ntarda lo mismo tanto si las cadenas difieren al principio como al final; la\ndocumentación de GitHub indica que nunca se deben comparar firmas con un\nsimple `==`. Un manejador sólido sigue después un orden fijo: leer los bytes\nsin procesar, verificar la firma sobre esos mismos bytes, comprobar que la\nmarca temporal del intento es reciente si el productor firma una, comprobar\nsi ya se ha visto ese identificador de evento, poner el evento en una cola y\nresponder con un 2xx. El trabajo real se hace después. Stripe pone el ejemplo\nde devolver un 200 antes de marcar como pagada una factura del cliente en el\nsistema contable.\n\nDos proyectos del portafolio de este sitio trabajan con webhooks desde el\nlado receptor. En las\n[autorizaciones para Stripe y compras dentro de aplicaciones](/es/portfolio/built-stripe-and-in-app-purchase-entitlements/),\nuna suscripción debe soportar, entre otras cosas, un webhook que llega dos veces\ny otro que llega fuera de orden. En el\n[sistema de correo con conmutación y registro de entregas](/es/portfolio/built-email-with-failover-and-delivery-logging/),\nlos webhooks entrantes informan de lo que cada proveedor hizo con un mensaje;\nel proyecto registra tanto lo enviado como lo recibido en un registro de envíos\ny una tabla de eventos de entrega.\n\n## Dónde surgen los problemas\n\n**La firma nunca coincide.** Una causa habitual es que el framework receptor\nanalice el cuerpo JSON y el código lo serialice otra vez antes de calcular el\nHMAC. La especificación lo considera un fallo muy común: la serialización JSON\nvaría entre implementaciones, y un solo espacio de más invalida la firma.\nStripe necesita el cuerpo sin procesar por la misma razón y advierte de que\ncualquier manipulación hace fallar la verificación. GitHub añade que un proxy\no balanceador situado delante del receptor no debe modificar la carga útil ni\nlas cabeceras, y que la carga debe tratarse como UTF-8. Calcule la firma sobre\nlos bytes exactamente como llegaron, antes de que nada los analice.\n\n**El mismo evento llega dos veces.** Tanto los reintentos como los problemas\nde red generan duplicados. Según la especificación, `webhook-id` no cambia\nentre los reintentos de un evento y sirve como clave de idempotencia; su ejemplo\nconsiste en guardar los identificadores en Redis durante cinco minutos. Stripe\nindica que se registren los identificadores de eventos procesados y se omitan\nlos ya vistos. También señala que un mismo hecho puede producir dos objetos\nEvent distintos; se reconocen mediante el identificador del objeto en\n`data.object` junto con el tipo de evento. La cabecera `X-GitHub-Delivery` de\nGitHub no cambia cuando se repite una entrega. El procesamiento debe ser\nidempotente para que una segunda entrega no cambie nada.\n\n**Se reproduce una entrega interceptada.** Una firma válida sigue siendo\nválida, así que un atacante que intercepte una entrega puede enviarla otra vez.\nPor eso se firma la marca temporal: la especificación indica que se rechace\nun `webhook-timestamp` fuera de la tolerancia permitida. Las bibliotecas de\nStripe usan cinco minutos de forma predeterminada; Stripe advierte de que una\ntolerancia de 0 desactiva totalmente la comprobación y recomienda NTP para\nmantener preciso el reloj del servidor. Tanto Stripe como la especificación\nponen una marca temporal nueva en cada reintento: la antigüedad se mide desde\nese intento, no desde el evento original. Un intento retrasado puede quedar\nfuera de la tolerancia. Conserve los identificadores vistos al menos durante\nel plazo de tolerancia, y cualquier reproducción dentro de ese plazo se detecta\ncomo duplicado.\n\n**Los eventos llegan fuera de orden.** El ejemplo de Stripe: crear una\nsuscripción puede producir `customer.subscription.created`, `invoice.created`,\n`invoice.paid` y, si hay un cargo, `charge.created`, sin garantía de que lleguen\nen ese orden. El campo `created` de los eventos de instantánea de Stripe tiene\nresolución de un segundo, por lo que varios eventos pueden compartir marca\ntemporal; Stripe indica que no se use para ordenar eventos ni detectar\nduplicados. El enfoque sólido trata un evento como aviso de que algo cambió y\nobtiene el estado actual del objeto mediante la API antes de actuar.\n\n**El manejador es demasiado lento.** GitHub espera un 2xx en 10 segundos;\ndespués cierra la conexión y considera fallida la entrega. La especificación\nrecomienda un tiempo de espera de entre 15 y 30 segundos para la petición.\nUn manejador que hace el trabajo real antes de responder agota ese plazo,\nel productor reintenta y el trabajo se hace dos veces. Stripe y GitHub\nrecomiendan una cola. Stripe señala el pico de principios de mes, cuando se\nrenuevan todas las suscripciones.\n\n**Solo cuenta un 2xx.** Tanto para la especificación como para Stripe,\ncualquier otro estado es un fallo, incluido un 3xx. Un punto de recepción que\nse ha trasladado detrás de una redirección falla en todas las entregas hasta\nque se actualiza su URL registrada. La especificación asigna significado a\nalgunos códigos para el productor: `410 Gone` indica que debe desactivar el\npunto de recepción; un 429, 502 o 504, que debe reducir el ritmo; y una cabecera\n`retry-after` debe orientar el siguiente intento.\n\n**Para el productor, la URL es una entrada hostil.** Los clientes pueden\nintroducir cualquier URL y los servidores del productor la llamarán. La\nespecificación considera los sistemas de webhooks especialmente vulnerables\na la falsificación de peticiones del lado del servidor, SSRF: una URL que\napunta a una dirección interna hace que el productor llame a su propia red.\nSu consejo es enviar todas las peticiones de webhook a través de un proxy que\nfiltre las direcciones IP internas, como smokescreen de Stripe, y ejecutar\nlos trabajadores de webhooks en una subred privada que no pueda alcanzar los\nservicios internos.\n\n## Lecturas adicionales\n\n- [Standard Webhooks specification](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md)\n  — versión 1.0.0: estructura de la carga útil, método de firma, cabeceras,\n  calendario de reintentos, estados HTTP y SSRF.\n- [Receive Stripe events in your webhook endpoint](https://docs.stripe.com/webhooks)\n  — cargas reducidas y de instantánea, reintentos, eventos duplicados o\n  desordenados y protección frente a reproducciones.\n- [Best practices for using webhooks](https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks)\n  — lista de GitHub: pocos eventos, un secreto de webhook, HTTPS, respuesta\n  en 10 segundos, repetición de entregas y `X-GitHub-Delivery`.\n- [Validating webhook deliveries](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries)\n  — `X-Hub-Signature-256`, comparación en tiempo constante y un ejemplo para\n  comprobar el verificador.\n\n\u003chttps://engineer.company/es/glossary/webhook/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"Cómo un servicio avisa a su servidor de un evento, cómo es una entrega firmada y por qué el receptor debe prever duplicados y reintentos.","formats":{"gemtext":"https://engineer.company/es/glossary/webhook/index.gmi","gopher":"https://engineer.company/es/glossary/webhook/gophermap","html":"https://engineer.company/es/glossary/webhook/","json":"https://engineer.company/es/glossary/webhook/index.json","markdown":"https://engineer.company/es/glossary/webhook/index.md","pdf":"https://engineer.company/es/glossary/webhook/index.pdf"},"kind":"page","language":"es","title":"¿Qué es un webhook?","url":"https://engineer.company/es/glossary/webhook/","version":1}