Key Takeaways
- TypeScript webhook receivers verify HMAC on the raw body over HTTPS — not an npm “Complete TypeScript SMS SDK.”
- Return 2xx after durable idempotent persist; process slow work async.
- Accept ≠ delivered; map DLR events carefully.
- Same physics as Node/PHP webhook guides — different runtime.
- Developer Center owns live REST fields and signature header names.
- BYO Android and operator credit. We meter devices and volume (Free 300 lifetime; paid from $19/mo).
Summary
Receive webhooks from an Android SMS gateway API in TypeScript over REST. Hub: Android SMS Gateway API. Product: webhook overview. Docs: Developer Center. PHP sibling: PHP receive webhook.
An npm package that logs the OTP body “for debugging” is not a TypeScript best practice. It is a leak with types.
REST webhook, not an SDK
No official TS SDK product. Use your framework’s raw-body access + crypto. Confirm signature header names in Developer Center.
// Conceptual — confirm header/field names in Developer Center
const raw = req.rawBody; // Buffer
const ok = timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
if (!ok) return res.status(401).end();
// upsert event id, then 200Context
Webhooks are at-least-once. Pairing health still lives on the phone — setup.
Receive path
- TLS only.
- HMAC on raw bytes before business JSON use.
- Idempotent upsert by event/message id.
- DLR precedence in one mapper.
- Occasional poll reconciliation.
Handler table
| Step | Do | Do not |
|---|---|---|
| Auth | timingSafeEqual HMAC | Trust IP allowlist alone |
| Body | Raw bytes for MAC | Re-stringify then verify |
| Response | 2xx after durable write | Await CRM for 30s |
| Secrets | Env webhook secret | Commit secret in repo |
Webhooks do not buy airtime
Events are free of carrier cost; the original send spent airtime and metered volume. Free 300 lifetime; paid from $19/mo. Pricing.
Operations
Alert on signature failures and handler 5xx. Label multi-device metrics when device id is present.
HMAC and least privilege
Separate webhook secrets from send API keys. Rotate on staff change.
Decision guide
Prefer webhooks for realtime UX; keep GET status for gaps.
Checklist
- Raw-body HMAC; idempotent store; fast 2xx.
- No TS SDK product claim; no OTP in logs.
- No Unlimited SMS titles.
Next steps
Vonage deliverability comparison: Vonage vs Android SMS gateway.
Related product pages
Jump to the live product docs for this topic—not another long-form article.
- SMS webhook integrationInbound and status events
- SMS API documentationLive endpoint reference
- device and SMS volume pricingPlans and allowances
- Android SMS gateway product guideDefinition, product, and how to buy
