# webhook

## Qué es

Un webhook es una petición HTTP que un servicio envía a otro en el momento
en que ocurre algo en su lado: se procesa un pago, se abona una factura o
termina una tarea larga. El receptor registra de antemano una URL y el emisor
publica en ella una descripción de cada evento. La especificación Standard
Webhooks presenta «webhook» como «un nombre común para las llamadas de retorno
HTTP» y describe estos mecanismos como un canal por el que un servicio anuncia un evento a otro. A veces el término
se escribe en dos palabras, web hook, pero Stripe, GitHub y la especificación
lo escriben en una sola.

La especificación también describe un webhook como parte de la API de un
servicio, una especie de API al revés. Normalmente el cliente llama al servicio
cuando quiere algo. Con un webhook, el servicio llama al cliente cuando tiene
novedades. En una integración habitual de API, ambos lados ejecutan servidores
HTTP: uno para recibir llamadas de API y otro para recibir webhooks. Un servicio
también puede enviar webhooks sin ofrecer su propia API de peticiones. El emisor
se llama productor, el receptor consumidor, y la URL que registra el receptor
es su punto de recepción de webhooks.

La especificación recomienda un POST HTTP con un cuerpo JSON, pero no exige
un formato ni una estructura concretos para la carga útil. El cuerpo que propone
incluye un `type`, escrito con puntos y agrupado jerárquicamente, como
`invoice.paid`; un `timestamp` del momento en que ocurrió el evento, en ISO
8601; y los datos del evento bajo `data` o en el nivel superior. Puede haber
metadatos adicionales en ambos lugares. Los metadatos de entrega van en las
cabeceras: `webhook-id` identifica el evento, `webhook-timestamp` registra
cuándo se hizo este intento, en segundos Unix, y `webhook-signature` lo
autentica. Stripe y GitHub usan sus propios nombres de cabecera, entre ellos
`Stripe-Signature` y `X-Hub-Signature-256`, y sus reglas de verificación son
distintas: Stripe firma una marca temporal del intento junto con el cuerpo,
mientras que el HMAC de GitHub abarca solo el cuerpo.

La carga útil puede ser completa e incluir todo el objeto modificado, o
reducida y llevar poco más que un identificador, dejando que el receptor obtenga
el resto mediante la API. La especificación sopesa ambas opciones. Una carga
completa ahorra llamadas adicionales a la API. Una reducida supone menos datos
que generar y enviar, más flexibilidad y más margen para cambios posteriores:
siempre puede ampliarse hasta ser completa, pero no al revés. También permite
auditar el acceso a los datos, porque el receptor debe pedir expresamente lo
que lee. En cualquier caso, la especificación aconseja cargas pequeñas,
normalmente inferiores a 20 kB. Stripe ofrece un formato reducido y lo señala
como el recomendado.

## Por qué importa

Sin webhooks, un sistema que necesita conocer un cambio en otro lugar tiene
que realizar sondeos periódicos: preguntar una y otra vez, casi siempre para oír
que no ha ocurrido nada, y aun así enterarse del cambio solo en el siguiente
sondeo. Un webhook invierte el proceso. El servicio que conoce el evento
llama una vez, cuando ocurre. Así informan los proveedores de pagos, alojamiento
de código y correo electrónico a los sistemas construidos sobre ellos.

Invertir la dirección tiene costes, y la mayoría recaen en el receptor. Su
punto de recepción es una URL pública a la que cualquiera en internet puede
enviar un POST; nada en una petición entrante demuestra quién la envió, de modo
que la especificación exige verificar su autenticidad en cualquier
implementación segura. La entrega se reintenta hasta que el receptor responde
con un estado 2xx o la política de entrega deja de intentarlo. Por eso, el mismo
evento puede llegar más de una vez; Stripe advierte de que los receptores pueden
recibir duplicados ocasionalmente. Tampoco se promete el orden: Stripe indica
expresamente que no garantiza que los eventos lleguen en el orden en que se
generaron.

El productor, por su parte, debe seguir intentándolo. La especificación
recomienda un calendario de reintentos que abarque varios días, con espera
exponencial y una pequeña variación aleatoria. Su ejemplo hace diez intentos;
el último se realiza 75 horas, 35 minutos y 5 segundos después del primero. Stripe
reintenta durante un máximo de tres días en modo real. Un receptor que vuelve a estar disponible
dentro de ese plazo recibe automáticamente las entregas pendientes; después, Stripe permite reenviar
un evento manualmente hasta 15 días después de su creación, o hasta 30 días
mediante su CLI. Cuando la entrega falla durante mucho tiempo, la especificación
recomienda que el productor avise al consumidor por otro canal, como el correo
electrónico, y desactive el punto de recepción.

## Cómo se aplica en la práctica

Estas son las cabeceras de una entrega con el formato de la especificación.
El identificador, la marca temporal y la firma son los valores de ejemplo que
usa la propia especificación; el valor de `Host` y la ruta son inventados:

```http
POST /webhooks/billing HTTP/1.1
Host: example.com
Content-Type: application/json
webhook-id: msg_2KWPBgLlAfxdpx2AI54pPJ85f4W
webhook-timestamp: 1674087231
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
```

Este es el cuerpo, una carga reducida de la misma especificación, presentada
aquí con sangría para facilitar la lectura. Para transmitirla, la especificación
recomienda minificarla:

```json
{
  "type": "contact.created",
  "timestamp": "2022-11-03T20:26:10.344522Z",
  "data": {
    "id": "1f81eb52-5198-4599-803e-771906343485"
  }
}
```

El prefijo `v1` indica una firma simétrica: HMAC-SHA256 sobre el identificador
del evento, la marca temporal y el cuerpo unidos por puntos, con una clave
secreta exclusiva del punto de recepción. Como el identificador y la marca
temporal se firman junto con el cuerpo, ninguno puede cambiarse sin invalidar
la firma. La especificación también permite firmas asimétricas ed25519, marcadas
con `v1a`, y las recomienda cuando distintas partes se encargan de proteger al
productor y al consumidor.

GitHub también firma sus entregas con HMAC-SHA256, coloca el resumen hexadecimal
en `X-Hub-Signature-256` con el prefijo `sha256=` y publica un secreto, una
carga útil y una firma para probar un verificador. Este verificador en Python
se ha comprobado con ese ejemplo:

```python
import hashlib
import hmac


def verify(body: bytes, secret: str, header: str) -> bool:
    mac = hmac.new(secret.encode("utf-8"), body, hashlib.sha256)
    expected = "sha256=" + mac.hexdigest()
    return hmac.compare_digest(expected, header)


secret = "It's a Secret to Everybody"
header = (
    "sha256=757107ea0eb2509fc211221cce984b8a"
    "37570b6d7586c22c46f4379c8b043e17"
)
print(verify(b"Hello, World!", secret, header))  # True
print(verify(b"Hello, World! ", secret, header))  # False
```

Basta un espacio al final del cuerpo para que falle. `hmac.compare_digest`
tarda lo mismo tanto si las cadenas difieren al principio como al final; la
documentación de GitHub indica que nunca se deben comparar firmas con un
simple `==`. Un manejador sólido sigue después un orden fijo: leer los bytes
sin procesar, verificar la firma sobre esos mismos bytes, comprobar que la
marca temporal del intento es reciente si el productor firma una, comprobar
si ya se ha visto ese identificador de evento, poner el evento en una cola y
responder con un 2xx. El trabajo real se hace después. Stripe pone el ejemplo
de devolver un 200 antes de marcar como pagada una factura del cliente en el
sistema contable.

Dos proyectos del portafolio de este sitio trabajan con webhooks desde el
lado receptor. En las
[autorizaciones para Stripe y compras dentro de aplicaciones](/es/portfolio/built-stripe-and-in-app-purchase-entitlements/),
una suscripción debe soportar, entre otras cosas, un webhook que llega dos veces
y otro que llega fuera de orden. En el
[sistema de correo con conmutación y registro de entregas](/es/portfolio/built-email-with-failover-and-delivery-logging/),
los webhooks entrantes informan de lo que cada proveedor hizo con un mensaje;
el proyecto registra tanto lo enviado como lo recibido en un registro de envíos
y una tabla de eventos de entrega.

## Dónde surgen los problemas

**La firma nunca coincide.** Una causa habitual es que el framework receptor
analice el cuerpo JSON y el código lo serialice otra vez antes de calcular el
HMAC. La especificación lo considera un fallo muy común: la serialización JSON
varía entre implementaciones, y un solo espacio de más invalida la firma.
Stripe necesita el cuerpo sin procesar por la misma razón y advierte de que
cualquier manipulación hace fallar la verificación. GitHub añade que un proxy
o balanceador situado delante del receptor no debe modificar la carga útil ni
las cabeceras, y que la carga debe tratarse como UTF-8. Calcule la firma sobre
los bytes exactamente como llegaron, antes de que nada los analice.

**El mismo evento llega dos veces.** Tanto los reintentos como los problemas
de red generan duplicados. Según la especificación, `webhook-id` no cambia
entre los reintentos de un evento y sirve como clave de idempotencia; su ejemplo
consiste en guardar los identificadores en Redis durante cinco minutos. Stripe
indica que se registren los identificadores de eventos procesados y se omitan
los ya vistos. También señala que un mismo hecho puede producir dos objetos
Event distintos; se reconocen mediante el identificador del objeto en
`data.object` junto con el tipo de evento. La cabecera `X-GitHub-Delivery` de
GitHub no cambia cuando se repite una entrega. El procesamiento debe ser
idempotente para que una segunda entrega no cambie nada.

**Se reproduce una entrega interceptada.** Una firma válida sigue siendo
válida, así que un atacante que intercepte una entrega puede enviarla otra vez.
Por eso se firma la marca temporal: la especificación indica que se rechace
un `webhook-timestamp` fuera de la tolerancia permitida. Las bibliotecas de
Stripe usan cinco minutos de forma predeterminada; Stripe advierte de que una
tolerancia de 0 desactiva totalmente la comprobación y recomienda NTP para
mantener preciso el reloj del servidor. Tanto Stripe como la especificación
ponen una marca temporal nueva en cada reintento: la antigüedad se mide desde
ese intento, no desde el evento original. Un intento retrasado puede quedar
fuera de la tolerancia. Conserve los identificadores vistos al menos durante
el plazo de tolerancia, y cualquier reproducción dentro de ese plazo se detecta
como duplicado.

**Los eventos llegan fuera de orden.** El ejemplo de Stripe: crear una
suscripción puede producir `customer.subscription.created`, `invoice.created`,
`invoice.paid` y, si hay un cargo, `charge.created`, sin garantía de que lleguen
en ese orden. El campo `created` de los eventos de instantánea de Stripe tiene
resolución de un segundo, por lo que varios eventos pueden compartir marca
temporal; Stripe indica que no se use para ordenar eventos ni detectar
duplicados. El enfoque sólido trata un evento como aviso de que algo cambió y
obtiene el estado actual del objeto mediante la API antes de actuar.

**El manejador es demasiado lento.** GitHub espera un 2xx en 10 segundos;
después cierra la conexión y considera fallida la entrega. La especificación
recomienda un tiempo de espera de entre 15 y 30 segundos para la petición.
Un manejador que hace el trabajo real antes de responder agota ese plazo,
el productor reintenta y el trabajo se hace dos veces. Stripe y GitHub
recomiendan una cola. Stripe señala el pico de principios de mes, cuando se
renuevan todas las suscripciones.

**Solo cuenta un 2xx.** Tanto para la especificación como para Stripe,
cualquier otro estado es un fallo, incluido un 3xx. Un punto de recepción que
se ha trasladado detrás de una redirección falla en todas las entregas hasta
que se actualiza su URL registrada. La especificación asigna significado a
algunos códigos para el productor: `410 Gone` indica que debe desactivar el
punto de recepción; un 429, 502 o 504, que debe reducir el ritmo; y una cabecera
`retry-after` debe orientar el siguiente intento.

**Para el productor, la URL es una entrada hostil.** Los clientes pueden
introducir cualquier URL y los servidores del productor la llamarán. La
especificación considera los sistemas de webhooks especialmente vulnerables
a la falsificación de peticiones del lado del servidor, SSRF: una URL que
apunta a una dirección interna hace que el productor llame a su propia red.
Su consejo es enviar todas las peticiones de webhook a través de un proxy que
filtre las direcciones IP internas, como smokescreen de Stripe, y ejecutar
los trabajadores de webhooks en una subred privada que no pueda alcanzar los
servicios internos.

## Lecturas adicionales

- [Standard Webhooks specification](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md)
  — versión 1.0.0: estructura de la carga útil, método de firma, cabeceras,
  calendario de reintentos, estados HTTP y SSRF.
- [Receive Stripe events in your webhook endpoint](https://docs.stripe.com/webhooks)
  — cargas reducidas y de instantánea, reintentos, eventos duplicados o
  desordenados y protección frente a reproducciones.
- [Best practices for using webhooks](https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks)
  — lista de GitHub: pocos eventos, un secreto de webhook, HTTPS, respuesta
  en 10 segundos, repetición de entregas y `X-GitHub-Delivery`.
- [Validating webhook deliveries](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries)
  — `X-Hub-Signature-256`, comparación en tiempo constante y un ejemplo para
  comprobar el verificador.

<https://engineer.company/es/glossary/webhook/>
