To send an SMS from a Stripe webhook, verify the signature, switch on the event type, and send one text per event using the Stripe event ID as your idempotency key. Stripe delivers events at least once, so the same event can reach you twice, and the key is what stops the customer getting two texts.
We make Ready, so the send uses the Ready REST API and only the request shape we document. Only text customers who agreed to receive texts from you, and keep card or bank details out of the message.
The handler
import express from 'express';
import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const app = express();
app.post('/stripe-webhook', express.raw({ type: 'application/json' }), async (req, res) => {
let event;
try {
event = stripe.webhooks.constructEvent(
req.body, req.headers['stripe-signature'], process.env.STRIPE_WEBHOOK_SECRET);
} catch {
return res.status(400).end();
}
if (event.type === 'invoice.payment_failed') {
const invoice = event.data.object;
const phone = await lookupPhone(invoice.customer); // your database, E.164
if (phone) {
const r = await sendText(phone, 'Your payment didn\'t go through. Update your card: https://app.example/billing', event.id);
const code = r.status === 409 ? (await r.json().catch(() => ({}))).code : null;
// Not answered yet: let Stripe redeliver, and the same event ID gets the stored result.
if (r.status === 429 || r.status >= 500 || code === 'idempotency_in_progress') return res.status(503).end();
}
}
res.status(200).end();
});
async function sendText(to, body, key) {
return fetch('https://api.tryready.com/v1/messages', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-API-Key': process.env.READY_API_KEY, 'Idempotency-Key': key },
body: JSON.stringify({ to, body, consent_attested: true }),
signal: AbortSignal.timeout(10_000),
});
} express.raw matters. Stripe signs the exact bytes it sent, so a parsed and re-serialized body fails verification. Verify first, then act.
Why the event ID is a good key
Stripe event IDs are unique and stay the same when Stripe retries a delivery. Using one as the Idempotency-Key means a repeated delivery isn't texted twice, with no table of your own to track what you've already handled. If you also need a record for support, store the event ID with the outcome. Our idempotency post explains the lost-response case.
Answer Stripe fast
Return 200 once the send is answered, and a 5xx when it is not (a 429, a server error or a 409 idempotency_in_progress), so Stripe redelivers the event and the same key returns the first attempt's result. Return it quickly. If your handler waits on a slow carrier hop, Stripe times out and retries, which creates more work. For anything beyond a single send, write the event to a queue and process it from there, as in our queue design post.
Which events are worth a text
| Event | Text it? | Note |
|---|---|---|
invoice.payment_failed | Yes, first failure | Pair with email. Link to your billing page |
charge.succeeded receipt | Usually no | Email is the normal receipt channel |
payout.paid for your sellers | Optional | Only for those who opted in |
customer.subscription.trial_will_end | Yes | Short, with the date |
invoice.upcoming | Rarely | Email first |
Don't send a card number, even a partial one, a balance or a full invoice in a text. A link to a signed-in page is safer and fits the segment limit. For the dunning drip campaign itself, the recovery math post works through when a text beats an email.
FAQ
Can I use the Stripe CLI to test?
Yes. stripe listen forwards test events to your local endpoint, and a test key on the SMS side simulates every send with no card, number or charge.
What if my handler crashes after sending?
Stripe retries the event, your handler sends again with the same event ID as the key, and a repeated key means the request isn't sent twice, while Ready still remembers the key (the docs give the window). A resend from the Stripe dashboard after that window sends again, so check GET /v1/messages first.
Do payment texts need consent?
Yes. A payment failure notice is a transactional message, but you still need the customer's agreement to text them, and consent_attested is your statement that you have it.
The short version
Raw body, verify, switch on type, event ID as the key, answer fast. The messages API docs list every request field.
Cost and registration
A segment on the Standard rate is $0.0075 plus a $0.0045 carrier fee, passed through at cost, excluding optional screening. An account can send up to 500 texts a month before it registers for 10DLC, and most approvals take 2 to 7 days. See pricing for the full list.