Receiving messages

How inbound SMS is routed by shortcode and the exact JSON payload your webhook receives.

Receiving messages#

When someone sends an SMS to the Hep.gg number, the message is routed to your account by a shortcode and stored. If you have configured a webhook, the message is also pushed to your server in real time. To read stored inbound messages over the API instead, see Listing inbound messages.

Shortcode routing#

The first word of every inbound text is treated as the shortcode (lowercased) and selects which account the message belongs to. The remaining words become the message content.

ORDER large pepperoni
└─┬─┘ └───────┬───────┘
shortcode   content ("large pepperoni")

• The shortcode match is case-insensitive (the first word is lowercased before lookup).
• A message that is only a shortcode with no following words is valid; the content is then empty.
• If the shortcode does not match any account, the sender receives an automatic reply: The shortcode <code> does not exist. Please include it as the first word of your message. The message is still stored, but with no owner.

You claim a shortcode and set your webhook in the dashboard under SMS, Shortcode at hep.gg.

Webhook payload#

If you set a webhook URL for your shortcode, Hep.gg sends a POST to that URL for each matching inbound message.

The request is Content-Type: application/json. There is no Authorization header; the shared secret you configured is delivered inside the JSON body as the auth field. Compare auth against your expected secret to verify the call.

{
  "sender": "+447700900000",
  "auth": "your-configured-webhook-secret",
  "shortcode": "order",
  "messageContent": "large pepperoni"
}

Responding#

Return any 2xx status. Hep.gg records the HTTP status code it receives from your server (visible later on the inbound record as webhook_status) but does not retry on failure and does not require a specific response body. If no webhook is configured for the shortcode, no callback is made and the message is simply stored for you to read via the listing endpoint.

Example receiver#

curl -X POST https://your-server.example.com/sms-webhook \
  -H "Content-Type: application/json" \
  -d '{"sender":"+447700900000","auth":"your-secret","shortcode":"order","messageContent":"large pepperoni"}'

app.post("/sms-webhook", express.json(), (req, res) => {
  const { sender, auth, shortcode, messageContent } = req.body;
 
  if (auth !== process.env.SMS_WEBHOOK_SECRET) {
    return res.status(401).end();
  }
 
  console.log(`[${shortcode}] ${sender}: ${messageContent}`);
  res.sendStatus(200);
});

Inbound messages cost 0 credits.