Skip to main content
Belio can sign each USSD callback with HMAC-SHA256. Signing is optional. Until you generate a secret, callbacks are sent with Content-Type only. This is not your API client secret. Messaging delivery receipts use that secret. USSD uses a separate HMAC secret on the service channel. See callback security for delivery receipts. You can also reject traffic that does not come from Belio’s outbound IPs.

HMAC signing

Open the callback secret dialog on your USSD service in the Belio Cloud Portal. Generate a HMAC secret there. The plaintext secret is shown once. Copy it and store it with your application. Generating again rotates the secret. The previous value stops working immediately. After a secret exists, every POST to your callback URL includes:

How the signature is computed

The HMAC key is the secret you copied from the portal. The message is the timestamp, a dot, then the raw JSON body: HMAC-SHA256(hmac_secret, "{X-Timestamp}.{body}")\text{HMAC-SHA256}(\text{hmac\_secret},\ \texttt{"\{X\text{-}Timestamp\}.\{body\}"}) body is the exact JSON string Belio posts. Do not parse and re-serialize it before verifying. The digest is standard Base64, not URL-safe Base64.

Verify the signature

1

Read the headers

Extract X-Timestamp and X-Signature from the incoming request. If they are missing, reject the request when you expect signed traffic.
2

Check the timestamp

Reject the request if X-Timestamp is more than 5 minutes off from your clock. That limits replay of a captured request.
3

Recompute the signature

Using your USSD HMAC secret as UTF-8 bytes, compute:
Use the raw request body bytes. Do not pretty-print or reorder JSON fields.
4

Compare

Base64-encode your digest, strip the sha256= prefix from X-Signature, and compare. On a match, handle the session hop. On a mismatch, respond with 401 Unauthorized.
Compare signatures with a timing-safe function such as crypto.timingSafeEqual, hmac.compare_digest, or hash_equals. Ordinary string equality can leak whether the first bytes matched.

Code examples

IP whitelisting

You can reject requests that do not come from these addresses, at the network or in your handler. The same IPs send messaging and mobile data callbacks.