sendSMS webhook
This contract runs in the opposite direction: you host the endpoint, and Cheggout calls it. It exists for the referral microsite path, where there is no app session to inherit — the visitor enters a mobile number, and the OTP that logs them in is sent by you.
You own the SMS because you own the verified mobile number and your own sender identity. Cheggout does not send SMS on your behalf on this path.
Why it exists
Sharing a referral code is open — anyone can forward a link. Viewing referral history and claiming a reward is not. On the microsite there is no SSO, so the visitor has to prove who they are before the referral centre will show them anything. Mobile number plus OTP is that proof.
The endpoint you build
POST https://<your-domain>/sendSMS
The path shown is the documented convention. Register your exact URL with Cheggout during onboarding.
Request from Cheggout
| Field | Type | Description |
|---|---|---|
mobileNumber | string | The number the visitor entered |
channel | string | Your channel identifier |
{
"mobileNumber": "9XXXXXXXXX",
"channel": "YOURCHANNEL"
}
Your response
| Field | Type | Description |
|---|---|---|
status | string | Success or Failure |
reason | string | On failure — NOT FOUND, MULTIPLE REQUEST or OTHER |
otp | string | The OTP you sent to the customer |
virtualId | string | The customer's identifier in the Cheggout system |
{
"status": "Success",
"otp": "REPLACE_OTP",
"virtualId": "pub_8f14e45fceea167a"
}
{
"status": "Failure",
"reason": "NOT FOUND"
}
reason values
| Value | Meaning | What the visitor should see |
|---|---|---|
NOT FOUND | No customer matches that number on this channel | A neutral message — see the caution below |
MULTIPLE REQUEST | Too many OTP requests for this number | Ask them to wait before retrying |
OTHER | Anything else | A generic retry message |
What you do on receiving a call
- Resolve the mobile number to a customer on that channel. No match →
NOT FOUND. - Rate-limit by number. Over the limit →
MULTIPLE REQUEST. - Generate a short numeric OTP with a short expiry.
- Send it by SMS through your own sender.
- Respond with
status, theotp, and the customer'svirtualId.
Security
This contract has the verifying party receive the OTP directly, which means the code is not a shared secret between you and the customer alone. Two consequences you must not skip:
- The endpoint must be authenticated and IP-restricted. Anyone who can call it can request an OTP for an arbitrary mobile number and read it back. Restrict it to Cheggout's outbound addresses at your edge, and require a credential agreed at onboarding.
- Keep the OTP out of logs. Not in access logs, not in APM traces, not in support tooling.
TBD Cheggout's outbound IP list and the authentication mechanism for this webhook are not published. Ask for both before you expose the endpoint, and raise signature support if your security review requires it.
NOT FOUND tells the caller that a mobile number is not a customer of yours — and the microsite is
public. Show the visitor the same neutral "if this number is registered, you will receive a code"
message for NOT FOUND as for success, and keep the distinction to your logs.
Beyond that, apply the usual OTP hygiene: short expiry, low attempt limit, single use, and no reuse of a code across requests. See Security best practices.
Next
- Entry points — where this fits
- Refer & Earn
- Security best practices