Key Takeaways
- create_webhook via MCP fails on URL, secret, HTTPS, and timeouts — it wraps POST /webhooks, not a special plugin.
- HMAC mismatches are almost always your receiver (raw body, clock skew), not “the agent bypassed signing.”
- A 201 from the tool does not mean message.received will arrive. Pair the phone and grant SMS permissions separately.
- Do not implement webhook forgery. This page is ops: config, TLS, secrets in env.
- You bring the Android and airtime. We meter devices and volume.
MCP Server for Android SMS Gateway: Create_webhook via MCP — failure modes is the tool that should call https://app.sms-gateway.app/api/v1/webhooks. Happy-path HMAC: Java webhook receive. Overview failures: building overview. Live names: Developer Center. Spec: MCP.
Not a first-party plugin. Devices and send volume.
POST /webhooks
Registered is not delivered. HMAC is not optional.
create_webhook registers a URL, nothing else
The agent should not invent signing. Your wrapper POSTs JSON the OpenAPI documents. Events like message.delivered / message.received are listed there — not in a prompt.
If the tool “succeeds” and your endpoint never logs a POST, you registered the wrong host or lost TLS.
Webhook tool failure table
| Failure | Cause | Fix |
|---|---|---|
| 4xx from control plane | http:// URL, bad JSON | HTTPS + Developer Center fields |
| 401 HMAC on receive | Pretty-printed body / wrong secret | Raw bytes; secret in MCP env |
| stale_timestamp | Clock skew | NTP on the receiver |
| Tool timeout | Hung Http | Timeouts; do not retry-register in a loop |
| No inbound after 201 | Phone / permissions | Two-way SMS |
HTTP, HMAC, stale timestamps
Signing is X-SmsGateway-Signature over timestamp + body. Verify it. Do not publish bypass recipes. Clock skew looks like an attack; it is usually NTP. Audit lines should store event ids, not bodies.
Duplicates and silent no-ops
Agents love to “try again.” Two identical webhooks mean double POSTs to your app. Dedupe on destination URL + event types in your wrapper, or list-then-create. Idempotency here is yours.
Registration ≠ inbound SMS
Doze does not unregister webhooks. It just means message.received never fires because the modem never saw the reply. Setup · webhook in-depth.
Next steps
Register from a staging tool, send a staff inbound, confirm one HMAC 200. Install the app. 300 lifetime SMS is enough to prove the path.
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
