Ricevitore di webhook affidabile: firma, idempotenza, coda e retry

Prompt

Agisci come ingegnere backend esperto di integrazioni e sistemi distribuiti.

Devo ricevere webhook in modo affidabile:
- Fornitore e modalità di firma: {{fornitore}}
- Eventi che mi interessano e cosa faccio con ciascuno: {{eventi}}
- Stack: {{stack}}
- Sistema di code disponibile: {{coda}}

Consegna:
1. Un diagramma testuale del flusso: ricezione, verifica, salvataggio, accodamento, elaborazione, retry e coda dei falliti.
2. L’endpoint di ricezione:
   - Legge il body grezzo prima del parsing e verifica la firma HMAC con un confronto a tempo costante.
   - Rifiuta le richieste con timestamp fuori da una finestra breve, per evitare attacchi di replay.
   - Salva l’evento e risponde 2xx in pochi millisecondi; nessuna logica pesante nella richiesta.
3. Idempotenza: tabella degli eventi con l’id del fornitore come chiave univoca, stati (ricevuto, in lavorazione, completato, fallito) e cosa fare se lo stesso evento arriva due volte.
4. Worker: elaborazione con backoff esponenziale e jitter, numero massimo di tentativi, distinzione tra errori transitori e permanenti, e coda dei falliti con modo per rielaborarli.
5. Ordine di arrivo: come gestire eventi fuori sequenza (per esempio controllando versione o data della risorsa, o rileggendola dall’API del fornitore).
6. Log e alert: cosa registrare senza salvare dati sensibili e quali metriche tenere d’occhio.
7. Test: firma valida e non valida, evento duplicato, timestamp vecchio, errore transitorio che si risolve ed errore permanente che finisce nella coda dei falliti.
8. Come testare in locale (tunnel o inoltro degli eventi) senza esporre il segreto.

Vincoli:
- Non indovinare il formato esatto della firma né i nomi degli header del fornitore: se non li indico, segna [DA COMPLETARE] e dimmi dove trovarli nella documentazione.
- Il segreto si legge da variabili d’ambiente o da un secret manager, mai nel codice.
- Se mancano informazioni chiave, chiedimele prima di scrivere il codice.

Come usarlo

Esempio d'uso

Esempio di risultato

Gateway → POST /webhooks/pagamenti → verifica firma + timestamp → INSERT evento (unico)
        → commit → 200 → Celery: elabora → retry con backoff → dead-letter

@router.post("/webhooks/pagamenti")
async def ricevi(request: Request, db: AsyncSession = Depends(get_db)) -> dict:
    grezzo = await request.body()                     # body grezzo, prima del parsing
    ts = request.headers.get("[DA COMPLETARE: header timestamp]", "")
    firma = request.headers.get("[DA COMPLETARE: header firma]", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        raise HTTPException(400, "timestamp mancante o scaduto")

    # Formato del messaggio firmato secondo la doc del fornitore: [DA COMPLETARE]
    attesa = hmac.new(settings.webhook_secret.encode(),
                      f"{ts}.".encode() + grezzo, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(attesa, firma):        # confronto a tempo costante
        raise HTTPException(400, "firma non valida")

    evento = json.loads(grezzo)
    stmt = (insert(WebhookEvent)
            .values(provider_event_id=evento["id"], tipo=evento["type"],
                    payload=evento, stato="ricevuto")
            .on_conflict_do_nothing(index_elements=["provider_event_id"])
            .returning(WebhookEvent.id))
    nuovo_id = (await db.execute(stmt)).scalar_one_or_none()
    await db.commit()
    if nuovo_id is not None:                          # duplicato → non viene riaccodato
        elabora_evento.delay(nuovo_id)
    return {"ok": True}

Dati chiave

Categoria

Programmazione e sviluppo · API

Tipo di output

Codice

Livello

Avanzato

Pensato per

ChatGPT, Claude, Gemini e Microsoft Copilot

Verificato in

In attesa di verifica editoriale

Variabili

Fornitore e firma, Eventi e azioni, Stack e Sistema di code

Lingua

Italiano

Prezzo

Gratuito, senza registrazione

Aggiornato

07/11/2026

Domande frequenti