Skip to main content

sendSMS webhook

Available

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​

FieldTypeDescription
mobileNumberstringThe number the visitor entered
channelstringYour channel identifier
Request (synthetic)
{
"mobileNumber": "9XXXXXXXXX",
"channel": "YOURCHANNEL"
}

Your response​

FieldTypeDescription
statusstringSuccess or Failure
reasonstringOn failure — NOT FOUND, MULTIPLE REQUEST or OTHER
otpstringThe OTP you sent to the customer
virtualIdstringThe customer's identifier in the Cheggout system
Success (synthetic)
{
"status": "Success",
"otp": "REPLACE_OTP",
"virtualId": "pub_8f14e45fceea167a"
}
Failure (synthetic)
{
"status": "Failure",
"reason": "NOT FOUND"
}

reason values​

ValueMeaningWhat the visitor should see
NOT FOUNDNo customer matches that number on this channelA neutral message — see the caution below
MULTIPLE REQUESTToo many OTP requests for this numberAsk them to wait before retrying
OTHERAnything elseA generic retry message

What you do on receiving a call​

  1. Resolve the mobile number to a customer on that channel. No match → NOT FOUND.
  2. Rate-limit by number. Over the limit → MULTIPLE REQUEST.
  3. Generate a short numeric OTP with a short expiry.
  4. Send it by SMS through your own sender.
  5. Respond with status, the otp, and the customer's virtualId.

Security​

The OTP is returned in the response body — design around that

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.

Do not let the response confirm who banks with you

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​