Get SMS Codes Pushed to Your Server Instead of Polling the API

The npm SDK's waitForSms() helper works fine for a CI script or a one-off test — rent a number, poll every few seconds, get the code. But if you're integrating the REST API directly into a real backend, polling means either running a loop that ties up a request, or building your own job to check rental status on a schedule. Neither is great for something that should just show up.

What it does

Set a webhook URL on the API Access page, once. From then on, the moment an SMS lands on a rented number, we POST a JSON payload to that URL: { event: "sms.received", rentalId, phoneNumber, sms: { sender, body, receivedAt } }. No more calling GET /api/v1/rentals/{id} in a loop.

Every request is signed with HMAC-SHA256 using a secret shown once when you set the webhook — verify the x-smsflorin-signature header against your own copy of the secret to confirm a payload actually came from us before trusting it.

Setup

Go to API Access, generate an API key if you don't already have one, then set a webhook URL under the Webhook section. It has to be https:// and reachable from the public internet — we validate and reject anything pointing at a local or private address.

Regenerating your API key doesn't reset the webhook — it carries over automatically.

Delivery is best-effort

There's no retry queue yet — if your endpoint is down or slow when a code arrives, that delivery is dropped (a 5-second timeout, matching the SMS-received email/Telegram notifications we already send). The rental itself is unaffected either way; you can always fall back to GET /api/v1/rentals/{id} for the same data if a webhook delivery is ever missed.