Key Takeaways
- A failed-renewal webhook is a billing event. A “come back for 20% off” hook is marketing with STOP.
- Card-update OTP is authentication. It never shares the dunning SIM.
- Free is 1 device, 300 SMS lifetime, and 300 contacts. Platform price is devices plus send volume; retries still spend operator credit.
- Gift-card PIN SMS is high-risk — hashed or portal-only, never a CSV leftover.
- Idempotency is invoice-id plus attempt, not customer-id — monthly cycles replay.
Summary
Scenario 121 is ecommerce webhooks for subscriptions, dunning, and gift-card issuance — not checkout tracking and not COD. Billing systems retry. Gift-card apps emit “issued” twice. Your worker must treat those as hostile until signed and de-duplicated. Service pricing is devices plus SMS send volume. You bring the phone and operator credit. Free is 1 device, 300 SMS lifetime, and 300 contacts.
Business allows 15 devices: dunning, OTP, promo win-back, gift-card, region spares. Uncapped platform volume is not unlimited carrier SMS. Confirm events in Developer Center.
invoice.failed · card OTP · gift issued
attempt 2 is a new key, not a new customer
Dunning is not a win-back blast
Failed renewal: amount, next retry date, update-card link. No upsell. Win-back after cancel: promo ledger, STOP, quiet hours. If you fire win-back from the same consumer as invoice.payment_failed, you will coupon people who still intend to pay.
Transactional SMS, OTP, webhooks.
Billing providers retry the same invoice. If your idempotency key is only customer-id, month two never sends. If it is only invoice-id, attempt two is silent when you needed a second notice. Use both plus attempt.
Subscription webhook matrix
| Event | Lane | Failure |
|---|---|---|
| invoice.payment_failed | Dunning device, transactional | Coupon footer; STOP ignored later |
| customer.source.updated | Card-update OTP isolated | OTP on the dunning SIM during a retry storm |
| subscription.deleted | Optional confirm; then promo only if opted in | Immediate win-back without consent |
| gift_card.issued | PIN via portal or hashed one-shot | PIN in logs and in a replayed webhook |
Card-update OTP vs invoice SMS
Hash the code, short TTL, no gift-card language. Verify signatures. Live fields in Developer Center. DLR is accept, not “card updated.”
Gift-card issuance hooks
Prefer a one-time portal link. If you must SMS a code, treat it like OTP: no retries with a new code unless the first POST never accepted. Replay of issued is the common theft-of-attention bug, not a feature.
Devices, volume, and airtime
Renewal mornings are volume spikes. We meter devices and platform sends. The SIM’s operator meters the rest. Free (1/300/300) is a staging store.
Renewal-day operations
Pairing, charge, dunning vs OTP isolation, staff canary on a failed-invoice template (not a real customer). Setup, Downloads, pricing.
Decision guide
Ship when invoice+attempt keys, OTP isolation, and gift-card replay guards exist. Delay if marketing owns the billing webhook. No-phone-ops teams should use an aggregator and pay per message.
Subscription checklist
- Dunning copy has no coupon on attempt 1.
- Idempotency = invoice + attempt.
- Card OTP isolated.
- Gift-card PIN not logged; replay safe.
- Win-back is a separate consented lane.
- Developer Center fields confirmed.
Next steps
Gateway overview, scenario 1 checkout, scenario 61 COD, Google Ads SMS/MMS policy.
Related product pages
Jump to the live product docs for this topic—not another long-form article.
- SMS webhook integrationInbound and status events
- transactional SMS for orders and alertsEvent-driven messages
- SMS API documentationLive endpoint reference
- device and SMS volume pricingPlans and allowances
