Webhooks: cum afli că mesajul chiar a ajuns

Când trimiți un mesaj, API-ul răspunde imediat cu statusul scheduled sau sent. Asta înseamnă „am preluat mesajul", nu „a ajuns pe telefon". Confirmarea reală vine mai târziu, de la operator, printr-un callback către adresa ta.

Configurarea

Trimite un callback_url în payload-ul mesajului, sau setează unul implicit în cont. Calisero va face un POST către acea adresă de fiecare dată când statusul mesajului se schimbă.

{
  "id": "0197e8c5-2c11-72cf-8057-bca8f619bd52",
  "status": "delivered",
  "recipient": "+40712345678",
  "delivered_at": "2026-07-16T09:41:22.000000Z"
}

Răspunde repede, procesează mai târziu

Endpoint-ul tău trebuie să răspundă 200 în câteva sute de milisecunde. Nu actualiza baze de date, nu trimite e-mailuri și nu apela alte servicii în timpul request-ului.

Scrie evenimentul într-o coadă și returnează imediat. Procesarea se face asincron, de un worker. Dacă endpoint-ul tău răspunde greu, retrimiterile se acumulează și rămâi în urmă cu orele.

Tratează duplicatele

Callback-urile sunt livrate cel puțin o dată. O rețea instabilă, un timeout de o secundă sau un deploy în derulare pot produce același eveniment de două ori.

Fă procesarea idempotentă: folosește perechea id + status ca cheie unică și ignoră ce ai văzut deja. Nu presupune niciodată că un eveniment vine exact o dată.

Nu presupune ordinea

Evenimentele pot sosi în altă ordine decât s-au produs. Un delivered poate ajunge înaintea unui sent. Compară întotdeauna marcajul de timp din payload cu ce ai deja salvat și ignoră evenimentele mai vechi decât starea curentă.

Securizează endpoint-ul

Adresa de callback este publică. Tratează-o ca atare:

• folosește un URL greu de ghicit, cu un identificator aleatoriu în cale;
• acceptă doar POST și doar peste HTTPS;
• validează că id-ul primit corespunde unui mesaj pe care chiar l-ai trimis;
• nu expune date sensibile în răspuns.

Ce faci când callback-ul lipsește

Rețelele pică, serverele se restartează. Ține un job periodic care caută mesajele rămase fără status final mai mult de câteva ore și interoghează API-ul direct pentru starea lor. Webhook-ul este calea rapidă; interogarea este plasa de siguranță.