Retorna Gateway — Webhooks
Eventos que Retorna Gateway te envía. Todo el resto de esta documentación describe endpoints que tú llamas; este describe el endpoint que tú expones y que nosotros llamamos.
Hoy existe exactamente un evento: una orden cambió de estado.
Registrar tu endpoint
La URL (solo https) se define cuando se aprovisiona tu organización, y ese
mismo paso te entrega el webhookSecret — la clave con la que verificas las
firmas. Pídenos que apunte a otro lado si tiene que moverse.
El webhookSecret se muestra una sola vez y nunca más. No se puede
recuperar desde ningún endpoint. Guárdalo en el momento en que lo recibes; si
lo pierdes, hay que volver a aprovisionar el webhook.
Verificar la firma — haz esto antes que cualquier otra cosa
Cada entrega trae un header X-Retorna-Signature: el HMAC-SHA256 del body
crudo de la request, en hexadecimal, con tu webhookSecret como clave.
Calcula el hash de los bytes que recibiste. No parsees el JSON para volver a serializarlo: el orden de las claves y los espacios cambiarían, y la firma ya no coincidiría. La mayoría de los frameworks lo exponen como "raw body" o "buffer body".
import hmac, hashlib
def is_authentic(raw_body: bytes, header: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, header) # tiempo constante, a propósito
Compara en tiempo constante (hmac.compare_digest, crypto.timingSafeEqual).
Un == común filtra, byte por byte, cuánto de un intento adivinado era
correcto.
Trata una request sin firma o mal firmada como hostil: tu endpoint es público, y la firma es lo único que nos separa de cualquier otro que descubra la URL.
Responder
Responde 2xx una vez que aceptaste el evento de forma durable. Cualquier otra cosa — cualquier 4xx incluido — cuenta como falla y reintentamos.
Responde rápido: una entrega se abandona a los 10 segundos. Haz el trabajo después, fuera de la request. Si respondes 2xx y después fallas internamente, lo consideramos entregado y no volverás a saber de esa orden.
Reintentos, y qué pasa si tu servicio está caído
Una entrega fallida se reintenta hasta 3 veces con backoff exponencial. Si todas fallan, el evento vuelve a nuestra cola y el ciclo completo corre hasta 3 veces más antes de que el evento quede apartado para inspección manual.
Que haya re-entregas significa que el mismo evento puede llegar más de una
vez. Deduplica por eventId, que es estable en todos los intentos del mismo
evento.
Los eventos no llegan ordenados. Dos cambios de la misma orden pueden
llegar fuera de secuencia; confía en timestamp y status, nunca en el orden
de llegada.