Webhooks de GitHub con FastAPI

Validar la firma HMAC, encolar el evento y responder a GitHub en menos de 10 segundos.

Contenido
  1. Validar la firma
  2. El endpoint
  3. Eventos que manejo
  4. Probar en local
  5. Repositorio y recursos

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 body

Importante: 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

EventoAcción
pushDispara el despliegue si la rama es main.
pull_requestPublica un comentario con el entorno de preview.
releaseGenera 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

Repositorio y recursos

usuario/fastapi-github-webhooks Receptor de webhooks de GitHub con FastAPI, RQ y Redis. github.com Ver repo →