Webhooky
a stav doručení

Jak dnes zjistíte stav doručení

Po odeslání zprávy přes REST API dostanete id zprávy. Stav pak kdykoli zjistíte dotazem:

GET https://www.topsms.cz/api/sms/status/{id}
Authorization: Bearer VAS_CLIENT_ID:VAS_SECRET

• Odpověď obsahuje status (sent / delivered / failed / expired), časová razítka doručení či selhání a operátora příjemce
• Tytéž stavy vidíte v dashboardu v historii zpráv, včetně CSV exportu
• Detailní popis polí najdete v API dokumentaci

Push webhooky — HTTP POST při změně stavu

U API klíče si v dashboardu nastavíte webhook URL — při doručení, selhání nebo expiraci zprávy odeslané tímto klíčem pošleme na vaši URL HTTP POST s JSON payloadem. Bez pollingu.

• Payload: event („sms.status"), id, externalId, to, from, status (delivered / failed / expired), price, deliveredAt / failedAt, errorMessage, errorCode (strojový důvod nedoručení: expired, undelivered, rejected, deleted, unknown, repeated_failure, not_sent; popis v REST API dokumentaci), sentAt
• Podpis: hlavička X-TopSMS-Signature: sha256=HMAC-SHA256(body, webhookSecret) — secret vám zobrazíme při vytvoření API klíče s webhook URL (najdete ho i v detailu klíče)
• Doručování: 3 pokusy (ihned, +30 s, +2 min), timeout 5 s na pokus; očekáváme odpověď HTTP 2xx
• Ověření podpisu v PHP má připravené naše topsms-php (metoda verifyWebhookSignature)

Testování a log doručení

• Testovací webhook: v dashboardu v sekci API přístup u klíče otevřete Log a webhook, v záložce Nastavení webhooku zadáte nebo změníte URL a tlačítkem pošlete ukázkovou událost. Hned uvidíte, co odpověděl váš server.
• Log doručení: tamtéž najdete každý pokus o doručení (čas, stavový kód vašeho serveru, chyba, délka, celé tělo). Uchovává se 30 dní.
• Testovací klíč: zprávy odeslané testovacím klíčem se nedoručují ani neúčtují, ale za pár sekund přijde webhook se simulovaným stavem a polem "test": true. Čísla končící 0000 simulují selhání, 0001 expiraci.
• Podpisový klíč (webhook secret) vzniká při prvním nastavení URL a zkopírujete ho u klíče v tabulce. Podpis ověřujte vždy, i u testovacích událostí.

Doporučený vzor: polling bez zbytečné zátěže

SMS se typicky doručí do několika sekund. Rozumný postup: po odeslání se na stav zeptejte po 10 sekundách, pak po 30 a 60 sekundách, a zbývající zprávy dokontrolujte jednou za pár minut. Konečné stavy (delivered, failed, expired) se už nemění — dotazování na ně můžete ukončit.

• Ukládejte si id každé odeslané zprávy
• Interval dotazů: 10 s → 30 s → 60 s → dále po minutách
• Konečný stav = konec pollingu pro danou zprávu
• Hromadné kampaně: stavy pohodlněji v dashboardu / CSV exportu