Secure an SMS API with three habits: keep the API key out of source control and client code, verify every webhook signature against the raw request body, and make your handlers safe to run twice. Most SMS incidents trace back to one of those three.

This guide covers each in turn. For Ready, requests carry an X-API-Key header, sends accept an Idempotency-Key, and every webhook carries an X-Signature header you verify with your webhook secret. The webhook docs are the source of truth for payloads, and the rest here is general good practice that applies to any provider.

What authenticates a request

Ready authenticates API calls with a key in the X-API-Key header, against the base URL https://api.tryready.com. Here's a send:

POST https://api.tryready.com/v1/messages
X-API-Key: <key>
Idempotency-Key: <a new UUID for each text>

{"to": "+12125550199", "body": "Your order #1042 has shipped.", "consent_attested": true}

That key can send texts that cost money, so treat it like a password. For the basics, see what an SMS API and API key are.

Storing and handling keys

Keep the key in an environment variable or a secrets manager, never in a repository, a mobile app or browser code. A key in client code is a key you've published.

Good practice for any provider:

  • One key per environment, so a leaked staging key can't send production traffic.
  • Keep keys out of logs, error trackers and support screenshots.
  • Rotate on a schedule and immediately after anyone with access leaves.
  • Call the API from your server, never from a browser.

Check the docs for how Ready issues and revokes keys, since we won't guess at the details here. If you build on a multi-tenant product, our multi-tenant SMS architecture post covers keeping tenants apart in shared code.

Limit what each key can touch when your provider allows it, and watch for unusual sending volume. A sudden jump in segments is often the first sign of a leaked key, and it shows up on the bill before anyone files a ticket.

Idempotency is a security feature too

An Idempotency-Key with a new UUID per text means a retried request, within the 7 days Ready keeps it, returns the first answer instead of sending again. That's a cost control and a safety control. A timeout in your job runner shouldn't turn into two texts to a customer's contact, or two charges.

Generate the UUID once per logical message and reuse it on every retry of that message.

Why webhooks need verification

A webhook URL is a public endpoint. Without verification, anyone who finds it can post fake inbound texts, fake opt-outs or fake delivery results into your system. The fix is a signature: the provider signs each request with a shared secret, and you check it before trusting the body.

Ready signs every webhook with X-Signature: sha256=<hex>, where the hex is the lowercase HMAC-SHA256 of the exact raw request body, keyed with your whole signing secret (the whsec_ prefix included). The docs have working Node and Python samples. The pattern below is the same one HMAC-style verification follows across providers.

const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
const ok = signature.length === expected.length &&
  crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

The verification pattern

  1. Read the raw body. Compute the signature over the exact bytes you received, before JSON parsing. Re-serializing changes the bytes and breaks the match.
  2. Recompute the signature with your secret using the algorithm the provider documents.
  3. Compare in constant time, using your language's secure comparison, not an equals sign.
  4. Limit replay. Ready sends no timestamp header, so drop repeats by the X-Ready-Event-Id header, and check the timestamp field inside the signed body after the signature.
  5. Respond fast with a 2xx, and do the real work from a queue.

Reject anything that fails with a 4xx and log the attempt. Don't reveal why it failed in the response body.

Test your verification with a bad signature before launch. Send a request with a wrong secret and confirm it's rejected, then send a valid one and confirm it's accepted. A check that has never failed in a test hasn't been shown to work.

Retries and duplicate delivery

Providers retry when you time out or return an error, so your handler will see the same event more than once. Deduplicate on the provider's message identifier before you act. Our inbound webhooks guide goes deeper on queues and reconciliation.

A reconciliation job helps too. You can read messages back from GET /v1/messages and compare them with what your webhooks delivered, which catches an event you missed.

Opt-outs in the security picture

Opt-out handling is a trust boundary. A forged STOP event could suppress a real customer, and a missed one could cause an unwanted text. Verify the signature first, and for any number you're unsure about, check GET /v1/opt-outs/:phone before a send.

A short checklist

CheckDone when
Key storageIn a secrets manager, absent from the repo
EnvironmentsA separate key for each
RotationScheduled, with an owner
Webhook signatureVerified over the raw body
DuplicatesDeduplicated by message ID
SendsCarry an Idempotency-Key

Compliance still sits with the sender, and keeping health details out of texts is your job because Ready isn't HIPAA compliant. To start, sign up and follow the quickstart. It covers a key, a first send and a webhook.