Che cosa sono i webhook?

Un webhook è un callback HTTP automatico: quando si verifica un evento, un sistema invia in POST un payload a un URL registrato da un altro sistema. Il termine – coniato nel 2007 come “user-defined HTTP callbacks” – dà il nome all’inversione che conta: invece di chiedere di continuo se qualcosa è cambiato, è l’altro sistema ad avvertire nell’istante in cui accade. È push costruito con i pezzi più banali del web: un URL HTTPS, un POST, un corpo JSON e una conferma 2xx.

Punti chiave

La consegna, da un capo all’altro

CONFIG    il ricevente espone  https://api.example.com/hooks/payments
          e lo registra presso il provider, scegliendo eventi + un segreto

EVENTO    un pagamento va a buon fine presso il provider

CONSEGNA  POST /hooks/payments
          webhook-id: evt_8fk2            ← chiave di deduplicazione
          webhook-timestamp: 1767024900   ← guardia anti-replay (dentro la firma)
          webhook-signature: v1,d2Vio…    ← HMAC-SHA256(secret, id.timestamp.body)
          { "type": "charge.succeeded", "orderId": "o-1187" }

ACK       il ricevente verifica la firma → 200 in pochi secondi → il lavoro va in async
RETRY     nessun 2xx? backoff esponenziale per ore/giorni → i duplicati sono NORMALI

Entrambe le direzioni del pattern in codice – un trigger sui dati come mittente, una Cloud Function come ricevente e il client che si limita a osservare il risultato:

// JavaScript — Cloud Code (cloud/main.js): both directions of a webhook
// OUTGOING: any data change can notify an external system
Parse.Cloud.afterSave('Order', async (req) => {
  if (req.object.get('status') !== 'paid') return;
  await Parse.Cloud.httpRequest({
    method: 'POST',
    url: 'https://hooks.example.com/orders', // the receiver's registered URL
    headers: { 'Content-Type': 'application/json' },
    body: { event: 'order.paid', id: req.object.id },
  });
});

// INCOMING: a Cloud Function is a ready-made webhook receiver
Parse.Cloud.define('paymentWebhook', async (req) => {
  verifySignature(req.params, process.env.WEBHOOK_SECRET); // HMAC first
  await markOrderPaid(req.params.orderId); // write fast, work async
  return { received: true }; // 2xx before heavy processing
});

// Flutter / Dart — Back4app Flutter SDK
// The client's side of a webhook: watch its effect in real time
// (payment platform → Cloud Function receiver → database → Live Query → UI)
final orderQuery = QueryBuilder<ParseObject>(ParseObject('Order'))
  ..whereEqualTo('objectId', orderId);
final sub = await LiveQuery().client.subscribe(orderQuery);
sub.on(LiveQueryEvent.update, (order) {
  if (order.get<String>('status') == 'paid') showReceipt();
});
// The webhook itself was handled server-side — clients just watch the data.

// iOS / Swift — Back4app Swift SDK
// The client's side of a webhook: watch its effect in real time
// (payment platform → Cloud Function receiver → database → Live Query → UI)
let orderQuery = Order.query("objectId" == orderId)
let sub = try await orderQuery.subscribe()
sub.handleEvent { _, event in
    if case .updated(let order) = event, order.status == "paid" {
        showReceipt()
    }
}
// The webhook itself was handled server-side — clients just watch the data.

// Android / Kotlin — Back4app Android SDK
// The client's side of a webhook: watch its effect in real time
// (payment platform → Cloud Function receiver → database → Live Query → UI)
val orderQuery = ParseQuery.getQuery<ParseObject>("Order")
orderQuery.whereEqualTo("objectId", orderId)
val sub = ParseLiveQueryClient.Factory.getClient().subscribe(orderQuery)
sub.handleEvent(SubscriptionHandling.Event.UPDATE) { _, order ->
    if (order.getString("status") == "paid") showReceipt()
}
// The webhook itself was handled server-side — clients just watch the data.

Webhook vs. API vs. polling

Il dibattito è in gran parte falso: le integrazioni mature usano tutti e tre – i webhook per sapere in fretta dei cambiamenti, le chiamate API per leggere lo stato che fa fede e agire, e un poll lento di riconciliazione come rete sotto il trapezio.

La checklist di chi riceve

L’elenco che la documentazione di ogni provider sparpaglia e che nessuna spiegazione mette insieme:

1. Verificare l’HMAC sul corpo grezzo – prima del parsing; il JSON riserializzato rompe le firme.
2. Confrontare in tempo costante – l’uguaglianza fra stringhe lascia filtrare informazioni dai tempi; conviene usare il comparatore della propria libreria di crittografia.
3. Applicare la finestra di timestamp – rifiutare le consegne più vecchie di ~5 minuti; poiché il timestamp sta dentro il contenuto firmato, un attaccante non può rigiocare una vecchia richiesta validamente firmata con un orologio fresco.
4. Restituire 2xx in fretta – entro pochi secondi, prima del lavoro pesante; gli handler lenti finiscono in timeout e vengono ritentati fino a diventare tempeste di duplicati.
5. Elaborare in modo asincrono – accodare, confermare, poi lavorare.
6. Deduplicare per ID dell’evento – con una memoria almeno lunga quanto la finestra di retry del provider.
7. Non fidarsi del payload per le azioni critiche – il webhook va trattato come un campanello: lo stato corrente si rilegge dall’API del provider prima di spedire merce o concedere un accesso.
8. Registrare le consegne e allertare sui fallimenti – il silenzio è indistinguibile da un endpoint rotto.

Una nota sullo sviluppo locale che le pagine definitorie saltano: localhost è irraggiungibile da internet, quindi lo sviluppo passa da uno strumento di tunneling che presta alla macchina un URL pubblico, più uno strumento di capture per rigiocare payload reali.

Semantica della consegna, onestamente

La consegna dei webhook è at-least-once: il provider ritenta finché non riceve conferma, quindi i duplicati sono una caratteristica dell’affidabilità, non un difetto – la consegna exactly-once su una rete inaffidabile è formalmente impossibile, e l’equivalente pratico è at-least-once più un handler idempotente. L’ordine non è garantito: retry e invii paralleli si intrecciano, quindi updated può arrivare prima di created; gli eventi vanno applicati per ID e versione, oppure si rilegge lo stato. E le finestre di retry finiscono: un endpoint fuori servizio per un fine settimana può perdere eventi in modo definitivo, ed è per questo che le integrazioni critiche in cui girano soldi abbinano i webhook a una riconciliazione periodica – la stessa disciplina at-least-once che i broker formalizzano, recapitata su semplice HTTP. Il confronto si generalizza: un webhook è push punto a punto verso un URL noto; il pub/sub aggiunge un broker, i topic e il fan-out; WebSocket e SSE servono i client, non i server. I webhook sono la risposta precisamente quando due sistemi che non condividono infrastruttura devono sapere degli eventi l’uno dell’altro.

Costruire il lato di chi invia

Emettere webhook in modo affidabile è un piccolo sistema a sé, e nessuna pagina di classifica lo abbozza: una coda per destinazione, così che un endpoint morto non blocchi gli altri; retry con backoff esponenziale e jitter; un archivio dead-letter con strumenti di riconsegna quando i tentativi si esauriscono; firma HMAC con segreti per singolo endpoint e rotazione; sottoscrizioni per tipo di evento, così che chi riceve scelga ciò che vuole; e registri di consegna leggibili dai clienti, perché “è stato inviato?” è la prima domanda che arriva al supporto. Un punto di sicurezza tipico di chi invia: i riceventi registrano URL arbitrari, quindi vanno validati contro gli intervalli di indirizzi interni – un attaccante che registra http://10.0.0.5/admin come proprio “endpoint di webhook” è server-side request forgery travestita da funzionalità di integrazione.

Casi d’uso tipici

• Cicli di vita dei pagamenti – addebiti, rimborsi e cambi di abbonamento annunciati al backend mentre si definiscono.
• Trigger di CI/CD – il collegamento canonico del git push che avvia una build.
• Automazione fra applicazioni – strumenti per i moduli, piattaforme di chat e CRM concatenati attraverso gli eventi gli uni degli altri.
• Notifiche operative – avvisi di monitoring e aggiornamenti di spedizione che atterrano nei canali del team.
• Sincronizzazione dei dati – mantenere aggiornato uno specchio locale di un sistema partner senza fare polling su tutta la sua API.

Conviene usare un webhook? Matrice decisionale

Limiti e trade-off

• Oltre la finestra di retry la consegna è best-effort. I webhook notificano; non garantiscono. I poll di riconciliazione coprono tutto ciò che non si può perdere.
• Chi riceve eredita il dovere di uptime. La disponibilità del proprio endpoint vincola ormai gli eventi di qualcun altro – deployment, cold start e timeout diventano tutti bug di integrazione.
• La sicurezza è opt-in. Un endpoint di webhook senza verifica è un’API di scrittura non autenticata; la checklist HMAC è la differenza fra integrazione e iniezione.
• Il debug si estende su due aziende. Registri di consegna da entrambe le parti e strumenti di replay sono ciò che trasforma “non è arrivato” da braccio di ferro in un diff.
• I payload derivano. I provider versionano gli schemi degli eventi; chi consuma si ancora a forme esatte e si rompe in silenzio – conviene fare parsing in modo difensivo e ignorare i campi sconosciuti.

I webhook su Back4app

Back4app è una piattaforma open-source di Backend as a Service (BaaS) che combina database gestito, API REST e GraphQL generate automaticamente, autenticazione, archiviazione di file e funzioni serverless con Cloud Code. Entrambe le metà del pattern distano un solo costrutto Cloud Code, come mostrano le schede di codice. In uscita: un trigger afterSave che osserva i dati chiama Parse.Cloud.httpRequest verso qualsiasi URL registrato – l’app diventa provider di webhook scrivendo la funzione, e le discipline del lato di chi invia (ritentare in caso di errore, registrare le consegne) vivono nello stesso file. In entrata: una Cloud Function esposta su HTTPS è un ricevente pronto all’uso – si verifica l’HMAC contro un segreto nella configurazione lato server, si scrive il risultato nel database, si risponde in fretta – e l’aggiornamento si propaga poi a ogni schermata aperta tramite le Live Queries, chiudendo il cerchio che va dall’evento di una piattaforma di pagamento alla ricevuta dell’utente senza un server da far girare in nessuno dei due passaggi.