Webhooks de GitHub con FastAPI
Validar la firma HMAC, encolar el evento y responder a GitHub en menos de 10 segundos.
GitHub espera una respuesta en menos de 10 segundos; si tardas más, marca la entrega como fallida. La regla es simple: validar, encolar y responder 202.
Validar la firma
Cada petición trae la cabecera X-Hub-Signature-256, un HMAC-SHA256 del cuerpo con tu secreto.
scriptpython
import hmac
import hashlib
from fastapi import HTTPException, Request
SECRET = os.environ["GITHUB_WEBHOOK_SECRET"].encode()
async def verify_signature(req: Request) -> bytes:
body = await req.body()
expected = "sha256=" + hmac.new(SECRET, body, hashlib.sha256).hexdigest()
received = req.headers.get("X-Hub-Signature-256", "")
if not hmac.compare_digest(expected, received):
raise HTTPException(status_code=401, detail="Firma inválida")
return bodyImportante: usa hmac.compare_digest, no ==, para evitar ataques de tiempo.
El endpoint
scriptpython
from fastapi import FastAPI, Request
from redis import Redis
from rq import Queue
app = FastAPI()
queue = Queue("github", connection=Redis())
@app.post("/webhook", status_code=202)
async def hook(req: Request):
body = await verify_signature(req)
event = req.headers.get("X-GitHub-Event", "ping")
delivery = req.headers.get("X-GitHub-Delivery")
queue.enqueue("workers.handle", event, body, job_id=delivery)
return {"queued": delivery}Usar X-GitHub-Delivery como job_id hace que las reentregas no se procesen dos veces.
Eventos que manejo
| Evento | Acción |
|---|---|
push | Dispara el despliegue si la rama es main. |
pull_request | Publica un comentario con el entorno de preview. |
release | Genera el changelog y lo publica en el blog. |
Probar en local
terminalbash
$ uvicorn app:app --reload --port 8000
$ gh webhook forward --repo=usuario/proyecto \
--events=push,pull_request --url=http://localhost:8000/webhook