Skip to main content

​
Operazioni sui Webhook

I Webhook sono il control plane. Questa pagina è il modello operativo pubblicato per la gestione dei webhook della piattaforma.

​
Principi Chiave

  • Verifica ogni delivery. Meta usa X-Hub-Signature-256; i hook dei partner possono usare HMAC o token statici.
  • Persisti gli envelope grezzi. Conserva header, hash del body, parametri di query e metadati tenant/provider secondo le policy di retention.
  • Normalizza verso famiglie di eventi conosciute. Usa provider.message.inbound, .status, .template.updated, .conversation.updated, ecc.
  • Esegui il replay in sicurezza. Ogni replay crea un nuovo record di tentativo senza modificare l’envelope originale.
  • Gestisci i duplicati. Deduplica per delivery ID ma mantieni il timestamp più recente e consenti il replay manuale quando si verificano miglioramenti legittimi.

​
Modello di Envelope

Ogni envelope registra:
  • tenant, provider, ambito del provider (WABA o numero di telefono)
  • famiglia dell’evento, ID evento esterno, delivery ID
  • stato di verifica e normalizzazione
  • header/parametri di query/hash del body/body grezzo
  • stato della risposta e metadati di replay

​
Endpoint Operativi

  • GET /internal/webhooks – filtra per tenant, tipo, cursore.
  • GET /internal/webhooks/:id – ispeziona header, body, stato dell’evento normalizzato.
  • GET /internal/webhook-rejections, /internal/webhook-rejections/:id – analisi forense.
  • POST /internal/webhooks/:id/replay – riprocessa dopo l’approvazione dell’operatore.
  • GET /internal/runtime – profondità delle code, lag dei worker, tendenze del backlog.

​
Monitoraggio

  • Latenza: obiettivo mediana sotto i 250 ms, con meno dell'1% delle richieste sopra 1 s.
  • Conteggi di rejection e replay.
  • Profondità della coda e heartbeat dei worker.
  • Tassi di fallimento della validazione dei template.
  • Violazioni dei guardrail su pair-rate e throughput.

​
Runbook

Vedi Operations Runbook per i passaggi di risposta agli incidenti, inclusi interruzione dei webhook, superamento dei rate-limit e fallimenti di campagne/journey.