Webhook e Notifiche di Consegna

Ci sono due modi per tracciare la consegna dei messaggi: polling e webhook. Scegli l'approccio più adatto al tuo caso d'uso.

Polling

Interroga lo stato di consegna su richiesta:

GET /messages/status/{customerMessageId}

Oppure controlla più messaggi contemporaneamente:

GET /messages/status?customerMessageIds=id1,id2,id3

Quando usare il polling:

• Volume di messaggi ridotto
• Controlli di stato occasionali
• Integrazioni semplici che non necessitano di un endpoint pubblico

Webhook

Registra un URL di callback HTTPS per ricevere aggiornamenti sullo stato di consegna in tempo reale, non appena il carrier li segnala.

Configura un webhook

POST /webhooks/delivery-status

Fornisci il tuo URL di callback. L'API invierà richieste HTTP POST a questo URL ogni volta che lo stato di un messaggio cambia.

Gestisci il tuo webhook

Azione	Endpoint
Ottieni webhook attuale	GET /webhooks/delivery-status
Crea webhook	POST /webhooks/delivery-status
Aggiorna URL webhook	PUT /webhooks/delivery-status
Revoca webhook	DELETE /webhooks/delivery-status

informazioni

È consentito un solo webhook di stato consegna attivo per account. Crearne uno nuovo sostituisce la configurazione precedente.

Payload del webhook

Quando lo stato di un messaggio cambia, l'API invia una richiesta POST al tuo URL di callback con un payload JSON contenente:

• messageId -- L'identificativo univoco del messaggio.
• customerMessageId -- Il tuo ID di riferimento personalizzato (se fornito durante l'invio).
• status -- Il nuovo stato di consegna (es. DELIVERED, SENT, ERROR, EXPIRED).
• timestamp -- Quando è avvenuto il cambio di stato.
• channel -- Il canale di messaggistica (SMS, RCS o WhatsApp).

Best practice

1. Usa HTTPS su un host pubblico -- L'URL di callback viene validato al momento della registrazione. Deve usare https sulla porta 443 (quella predefinita) o 8443, non deve contenere credenziali né frammenti #, e il suo host deve risolvere solo a indirizzi pubblicamente raggiungibili. Indirizzi di loopback, privati, link-local, carrier-grade-NAT e unique-local vengono rifiutati, così come gli host che non risolvono. Un URL che non supera uno di questi controlli viene rifiutato con 400.
2. Rispondi velocemente -- Restituisci una risposta 200 OK entro pochi secondi. Elabora il payload in modo asincrono se necessario.
3. Gestisci i retry -- Se il tuo endpoint non è raggiungibile, il sistema potrebbe ritentare la consegna. Rendi la tua elaborazione idempotente.
4. Valida la sorgente -- Verifica che i webhook in arrivo provengano da Qlara Platform API.
5. Monitora i fallimenti -- Se il tuo endpoint webhook fallisce costantemente, controlla i log del server e assicurati che l'URL sia accessibile.

Scegliere tra polling e webhook

Aspetto	Polling	Webhook
Latenza	Dipende dalla frequenza di polling	Quasi in tempo reale
Complessità	Semplici richieste GET	Richiede un endpoint HTTPS pubblico
Scalabilità	Aumenta le chiamate API a scala	Push-based, nessuna chiamata API extra
Ideale per	Volume ridotto, controlli occasionali	Volume elevato, dashboard in tempo reale

Consulta il Riferimento API Webhook e il Riferimento API Stato Consegna Messaggi per la documentazione completa degli endpoint.