Panoramica Webhooks

I webhooks ti permettono di ricevere notifiche HTTP in tempo reale quando si verificano eventi nel tuo account Replicer. Invece di interrogare l'API, configuri un URL endpoint e Replicer invia gli eventi a te.

Come funziona

1. Si verifica un evento (es. una chiamata termina)
2. Replicer trova i tuoi endpoint webhook attivi iscritti a quell'evento
3. Replicer invia una richiesta POST a ciascun endpoint con il payload dell'evento
4. Il tuo server risponde con 2xx per confermare la ricezione
5. Se la consegna fallisce, Replicer riprova fino a 5 volte con backoff esponenziale

Configurare i webhooks

Dalla Dashboard

1. Vai su Dashboard → Settings → Webhooks
2. Clicca su Add Endpoint
3. Inserisci l'URL del tuo endpoint (deve essere HTTPS in produzione)
4. Seleziona gli eventi che vuoi ricevere
5. Copia il signing secret — viene mostrato solo una volta

Requisiti dell'endpoint

• Deve accettare richieste POST con Content-Type: application/json
• Deve rispondere con un codice di stato 2xx entro 10 secondi
• Deve essere HTTPS in produzione (HTTP ammesso per lo sviluppo locale)

Formato del payload

Tutti gli eventi webhook vengono consegnati come JSON con un envelope consistente:

{
  "id": "evt-unique-delivery-id",
  "event": "call.ended",
  "timestamp": "2026-04-05T14:04:00Z",
  "data": {
    // Dati specifici dell'evento
  }
}

Header della richiesta

Header	Descrizione
Content-Type	application/json
X-Replicer-Event	Tipo di evento (es. call.ended)
X-Replicer-Delivery-Id	ID univoco della consegna
X-Replicer-Timestamp	Timestamp Unix della consegna
X-Replicer-Signature	Firma HMAC-SHA256 per la verifica

Politica di retry

Se il tuo endpoint non risponde con un codice di stato 2xx, Replicer riprova la consegna con backoff esponenziale:

Tentativo	Ritardo
1° retry	5 secondi
2° retry	30 secondi
3° retry	2 minuti
4° retry	10 minuti
5° retry	30 minuti

Dopo 5 tentativi falliti, la consegna viene contrassegnata come fallita. Puoi visualizzare la cronologia delle consegne nella dashboard.

Log delle consegne

Ogni tentativo di consegna viene registrato. Visualizza la cronologia in Settings → Webhooks → clicca sull'icona di consegna di un endpoint. Ogni voce di log include:

• Tipo di evento
• Codice di stato HTTP della risposta
• Numero del tentativo
• Stato successo/fallimento
• Timestamp