Evaluate GitHub App webhooks as primary event source

[pilipilisbot]

Context

IMAP-based GitHub notification ingestion is practical, but it depends on email formatting, mailbox UID state, auth headers, and delivery timing. GitHub webhooks provide signed, structured delivery ids and richer event context.

Proposal

Design and optionally implement a GitHub App/webhook ingestion path, keeping IMAP as fallback or compatibility mode.

Acceptance criteria

• Short design note compares webhook ingestion vs IMAP for trust, idempotency, latency, operational burden, and rollout.
• Event ids/delivery ids map cleanly to queue idempotency.
• Webhook signature verification is mandatory.
• IMAP remains supported during migration.

Priority

Medium.

[ecarreras]

@giscebot fes un anàlis de tot això ja que suposo que és un canvi crític, com es pot fer per fer-ho de forma gradual i que puguin conviure els dos sistemes, la idea és com crear una mena de clau única per esdeveniment i es processa el primer independentment de la font

[giscebot]

He revisat el flux actual (Notification -> Policy -> SQLite -> Executor). Ho considero un canvi crític, però es pot desplegar sense big bang si separem tres conceptes que ara estan parcialment barrejats:

1. Clau de recepció: deduplica reintents de la mateixa font. Per webhook seria X-GitHub-Delivery; per IMAP, Message-ID (el UID només és cursor de mailbox).
2. Clau canònica d'esdeveniment: identifica el mateix fet de GitHub independentment de la font. Aquesta és la clau que decideix «el primer guanya».
3. work_key: continua sent owner/repo#number i només serveix per serialitzar/coalescir treball del mateix fil. No és una clau d'esdeveniment: dos comentaris del mateix issue són fets diferents.

No faria servir el delivery ID com a clau global: deduplica retries del webhook, però mai podrà coincidir amb el correu. Tampoc derivaria una clau només de repo, número i acció, perquè una acció es pot repetir i provocaríem falsos duplicats.

Identitat canònica proposada

Per als casos que avui són accionables, la clau s'ha de construir amb IDs immutables de GitHub:

• issue_comment:created:<repo_id>:<comment_id>
• pull_request_review:submitted:<repo_id>:<review_id>
• pull_request_review_comment:created:<repo_id>:<comment_id>
• workflow_run:completed:<repo_id>:<run_id>:<run_attempt>
• per assignacions/review requests, incloure action, ID del subject i ID de l'actor/assignee/reviewer que fa l'acció.

El webhook ja porta aquests IDs. A IMAP, el parser extreu IDs de les URLs (issuecomment-*, pullrequestreview-*, discussion_r*, run ID); quan el correu no aporti prou dades, es pot enriquir amb l'API de GitHub. Si no podem demostrar que dos inputs són el mateix esdeveniment, no els fusionaria: fallback a una clau específica de font (email:<message-id> / webhook:<delivery-id>). És preferible algun duplicat excepcional a perdre feina legítima.

Model de persistència

Afegiria una capa d'ingesta comuna davant de la cua:

• ingest_receipts: source, source_key, hash/raw mínim, estat, timestamps; UNIQUE(source, source_key).
• github_events: event_key, context normalitzat, job_id, primer origen; UNIQUE(event_key).
• relació de receipts amb events per conservar auditoria i poder mesurar IMAP vs webhook.

En una única transacció SQLite:

1. persistir el receipt;
2. normalitzar i calcular event_key;
3. fer INSERT ... ON CONFLICT a github_events;
4. només el guanyador crea o coalesceix el job; el perdedor queda registrat com a duplicat del mateix event/job.

Això manté els invariants actuals de work_key i evita la cursa «arriben webhook i email alhora». Caldrà deixar de tenir jobs.message_id com a identitat global: ha de passar a ser metadada d'origen/compatibilitat. Els receipts i payloads complets han de tenir retenció limitada; després de completar el job, conservaria només claus, hashes, timestamps i resultat per no convertir SQLite en un arxiu etern.

Rollout gradual

Fase 0 — refactor intern sense webhook. Introduir receipt/event normalitzat i fer passar IMAP pel nou ingestor. Mateix comportament observable i tests de regressió.

Fase 1 — webhook shadow. Endpoint públic que verifica X-Hub-Signature-256 sobre els bytes crus amb comparació constant-time, persisteix abans de respondre 2xx i no crea jobs. Comparar durant 1–2 setmanes cobertura, latència i event_key contra IMAP. Alertar signatures invàlides, deliveries no normalitzables i divergències.

Fase 2 — dual ingest en canari. Activar enqueue des de webhook només per enabledRepos. IMAP continua exactament igual; amb la restricció única, el primer origen processa i l'altre només confirma/deduplica. No faria mark-seen automàticament fins validar que la cobertura és equivalent.

Fase 3 — webhook primari. Webhook processa immediatament. IMAP queda com a safety net, idealment amb retard curt per donar prioritat al payload estructurat però entrant pel mateix ingestor. Mètriques: percentatge d'events vistos per ambdues fonts, només webhook, només IMAP, conflictes de normalització, duplicates evitats i latència p95.

Fase 4 — fallback estable. Mantenir IMAP suportat i documentat; decidir més endavant si es deixa sempre actiu o només per incident/reconciliació. No l'eliminaria fins tenir almenys un cicle operatiu complet sense events accionables «IMAP-only».

Seguretat i operació

• GitHub App amb permisos mínims i subscripcions només als events suportats; la signatura valida origen, però igualment s'ha d'aplicar policy, enabledRepos, actor i installation/repository scope.
• Secret rotatable (actual + anterior durant una finestra), TLS/reverse proxy, límit de mida i content type; mai logar payloads amb secrets.
• Respondre ràpid després de persistència durable; classificació, API enrichment i dispatch són asíncrons. GitHub farà retries i delivery_id els absorbirà.
• Cal monitorar backlog, edat del receipt sense normalitzar, signatures fallides, taxa de fallback i diferències entre fonts.

Tests que considero obligatoris

• Mateix comentari: webhook primer / email primer / arribada concurrent => un únic event i un únic job.
• Retry del mateix delivery i correu duplicat => idempotència.
• Dos comentaris diferents al mateix PR => dos events, tot i compartir work_key.
• Mateixa acció repetida legítimament => no es perd.
• Payload amb signatura invàlida => ni receipt trusted ni job.
• Event no normalitzable => no es fusiona per aproximació.
• Caiguda després de persistir i abans d'enqueue => recuperació/reprocessament sense pèrdua.

La meva recomanació és obrir la implementació en tres PRs petites: (1) model receipt/event + migració d'IMAP, (2) endpoint webhook en shadow + observabilitat, (3) dual-ingest canari. Això deixa punts de rollback nets i permet validar la part més delicada —la identitat cross-source— amb dades reals abans que el webhook tingui efectes.

[ecarreras]

@giscebot implementa la FASE 0

[giscebot]

Fase 0 implementada a #225.

El PR introdueix receipts per font i una identitat canònica d'esdeveniment dins la mateixa transacció SQLite, fa passar IMAP pel nou ingestor i manté work_key separat per no confondre deduplicació amb serialització del fil. Quan no hi ha un ID immutable prou fiable, fa fallback a la clau de la font en lloc d'arriscar-se a perdre una acció legítima.

També inclou la nota de disseny i rollout gradual. Validació local: 371 passed (només un warning de deprecació de Starlette/httpx).

[giscebot]

La #225 ja està fusionada amb la CI verda i completa la Fase 0: model d’ingesta transport-independent, deduplicació canònica i migració del camí IMAP.

Aclariment important sobre aquesta clausura: encara no hi ha endpoint webhook ni GitHub App en producció. Les fases 1–4 (shadow amb verificació de signatura, dual-ingest canari, webhook primari i fallback estable) queden fora de #225. Interpreto, per tant, que #191 es tanca com a avaluació + fonament intern; si volem continuar la implantació, convé obrir issues separades per cada fase amb criteris i rollback propis, en lloc de presentar #225 com si tanqués tot el rollout.

[ecarreras]

@giscebot Implementa la Fase 1

[giscebot]

Fase 1 implementada a #226.

El PR afegeix el webhook en mode estrictament shadow: verifica X-Hub-Signature-256 sobre els bytes crus, accepta secret actual/anterior per rotacio, limita la mida, deduplica per X-GitHub-Delivery i persisteix nomes metadades, hash i clau canonica (mai el payload cru). Tambe exposa metriques autenticades de receipts, retries i coincidencies cross-source.

Limit deliberat: no crea jobs ni reclama github_events; IMAP continua sent la unica font que produeix feina. Els events edited queden observats amb identitat separada i no retriggeren res. Validacio local: 375 passed; CI del PR en curs.

[giscebot]

Punt pendent: inventari operatiu de webhooks configurats

El ping signat permet descobrir i guardar una fotografia sanejada de la configuració del webhook. Això no queda cobert per l'observabilitat agregada actual de la Fase 1: ara webhook_shadow_receipts no conserva hook_id i el dashboard només mostra totals globals.

Proposo afegir a aquesta fase/roadmap:

• Persistir un registre per webhook a partir del ping, identificat per hook.id / X-GitHub-Hook-ID, amb: tipus i target (organització o repositori), active, events subscrits, content_type, verificació SSL, URL de destí, created_at, updated_at i last_ping_at.
• No guardar mai el secret ni el payload cru. El secret: "********" del ping tampoc aporta cap valor operatiu.
• Capturar X-GitHub-Hook-ID en totes les entregues vàlides i actualitzar last_event_at, últim tipus/acció, repositori, delivery ID i resultat (observed, unsupported, duplicate). Així els receipts es poden consultar i agregar per webhook.
• Exposar al dashboard un inventari amb un estat informatiu per webhook: configurat/actiu segons l'últim ping, mai vist, rebent, inactiu o sense activitat recent. «Sense activitat recent» no s'ha de presentar com una avaria perquè un webhook pot estar correctament configurat però no generar events.
• Afegir un enllaç administratiu cap al webhook de GitHub, derivat del target i l'ID:
  • organització: https://github.com/organizations/{org}/settings/hooks/{hook_id}
  • repositori: https://github.com/{owner}/{repo}/settings/hooks/{hook_id}
    També es poden conservar hook.url, ping_url i deliveries_url com a URLs d'API.
• Permetre refrescar l'inventari reenviant un ping. Com a millora posterior, sincronitzar-lo amb l'API de GitHub quan disposem dels permisos administratius necessaris.

Notes de disseny:

• El ping és la font de configuració, però només arriba en crear/provar el webhook; per això cal mostrar last_ping_at i no assumir que la fotografia és sempre actual.
• La correlació de l'activitat posterior no ha de dependre del payload: GitHub envia X-GitHub-Hook-ID a cada delivery.
• Els intents amb signatura invàlida no haurien d'actualitzar l'estat del webhook inventariat; es poden comptar separadament com a seguretat.

Criteri d'acceptació proposat: després de rebre un ping i almenys una entrega real, la pestanya Webhooks mostra el webhook concret, la configuració sanejada, un enllaç a GitHub, l'últim event rebut i el seu estat/resultat.

[ecarreras]

@giscebot abans de passar a mode canari necessitem més informació al dashboard, veure els hooks rebuts, les configs, gràfiques. Dissenya un bon dashboard de recepció de webhooks pensant en com funcionarà

[giscebot]

Sí: abans del canari necessitem un dashboard que respongui “podem confiar en el webhook per aquest repo/event?”, no només quatre comptadors acumulats.

He revisat la Fase 1 actual. La pestanya només exposa receipts totals, duplicats, coincidències cross-source i mode; webhook_shadow_receipts tampoc guarda encara hook_id, timestamps d'actualització ni prou dimensió per construir cobertura i salut per hook. Proposo aquest disseny.

1. Capçalera: estat operatiu i finestra

Selector de finestra 1h / 24h / 7d / 30d (24h per defecte) i filtres per organització, repositori, hook, event i resultat. A dalt, sis KPI amb denominador explícit:

• deliveries vàlides rebudes;
• taxa de signatures invàlides (comptador de seguretat separat, sense tocar l'inventari);
• deliveries duplicades/retries;
• events canònics suportats;
• cobertura cross-source: events amb webhook + IMAP / events IMAP elegibles;
• latència p50/p95 webhook→persistència i IMAP→persistència.

No mostraria només “cross-source matches: N”: sense saber quants events IMAP elegibles hi havia, és enganyós.

2. Gràfiques que serveixen per decidir

• Deliveries en el temps, stacked per observed / duplicate / unsupported / rejected, amb granularitat adaptada a la finestra.
• Cobertura per font, amb quatre sèries: both, webhook-only, imap-only, unmatchable. Aquesta és la gràfica principal del shadow.
• Latència comparada, p50/p95 per font i, pels events vistos a ambdues, distribució de quin origen arriba primer i amb quanta diferència.
• Event mix, per família + action, separant canònics dels només observats. Això detecta una subscripció massa ampla o events que encara no sabem normalitzar.
• Resultats per hook/repo, preferentment heatmap o barres; no un donut ornamental.

Totes les gràfiques han de permetre obrir la llista de receipts que forma el punt/barra seleccionat.

3. Inventari de hooks

Una taula per hook, alimentada pel ping signat i X-GitHub-Hook-ID de cada delivery:

• owner/target i tipus (organization o repository);
• hook ID i enllaç administratiu a GitHub;
• active, SSL verify, content type i events subscrits;
• URL de destí sanejada;
• last_ping_at, last_event_at, últim event/action/repo/resultat;
• volum 24h, retries, unsupported i cobertura cross-source;
• estat derivat: never_seen, receiving, inactive, stale_config o quiet.

quiet ha de ser informatiu, no vermell: absència d'events no prova una avaria. stale_config significa que la fotografia del ping és antiga, no que GitHub estigui mal configurat.

En entrar al detall del hook: configuració sanejada, timeline d'activitat, repos coberts, distribució d'events i deliveries recents. Mai secret ni payload cru.

4. Explorer de deliveries i cua d'excepcions

Taula paginada server-side amb timestamp, hook, delivery ID, event/action, repo, canonical event key, resultat, duplicats, coincidència IMAP i latència. Filtres indexables i URL compartible.

A sobre, una cua curta i accionable:

• IMAP-only després d'una finestra de gràcia;
• webhook-only quan l'event era elegible per IMAP;
• event suportat sense clau canònica;
• mateix event key amb context/hash incompatible;
• retries anormalment alts;
• hook que envia events no seleccionats.

El detall pot ensenyar metadades i hashes, però no cossos de comentaris ni payloads. Les signatures invàlides s'agreguen per temps/causa; no les associaria a un hook inventariat perquè el header no és fiable fins verificar la signatura.

5. Model/API mínim

Separaria configuració, deliveries i agregats:

• webhook_hooks: fotografia sanejada del ping + last_ping_at/last_event_at;
• ampliar receipts amb hook_id, owner/target, updated_at, resultat i timestamps de processament;
• conservar la relació amb event_key/receipt IMAP per calcular cobertura;
• endpoints admin-only separats: /summary, /timeseries, /hooks, /hooks/{id}, /deliveries i /exceptions.

Les consultes han de ser paginades i agregades a backend; no carregaria milers de receipts al navegador. Cal definir retenció/rollups ara: receipts detallats 30 dies (configurable), agregats diaris més llargs, i conservar claus/hashes mínims per auditoria. Si canviem esquema, migració i validator/versionat corresponents.

6. Gate abans de Fase 2

No activaria canari fins que, per cada repo candidat i durant una finestra acordada:

• el hook aparegui inventariat i rebi deliveries signades;
• la cobertura de tots els tipus accionables sigui mesurable i no hi hagi IMAP-only sense explicar;
• retries, unsupported i errors de normalització siguin visibles des del dashboard;
• es pugui rastrejar un event des de les dues fonts fins a la mateixa event_key;
• auth admin del dashboard estigui provada explícitament per tots els endpoints nous;
• els llindars siguin configurables, no números màgics amagats a la UI.

Ho partiria en dues PRs abans del canari: (A) inventari + model/API/retenció, (B) UI amb overview, gràfiques, explorer i gate de cobertura. No barrejaria encara enqueue webhook: primer observabilitat verificable, després canvi de font primària.

[ecarreras]

@giscebot implementar la part de UI

[giscebot]

UI implementada a #229.

Afegeix tres vistes: Overview amb gràfica stacked i estats de receipts, Hooks amb inventari/configuració/estat, i Deliveries amb la traça recent. Manté els comptadors de la Fase 1 i mostra empty states explícits —no dades inventades— mentre el backend encara no retorni timeseries, hooks i recent_deliveries.

Validació: 55 tests del dashboard i build TypeScript/Vite correctes. No activa enqueue ni modifica el límit shadow de la Fase 1.