Skip to main content

Verifying webhooks and callbacks

Every webhook and every delivery callback HelloSMS sends is signed. There is nothing to switch on. Checking the signature proves that the call came from HelloSMS and that nobody has replayed or changed it on the way.

The signature follows the Standard Webhooks format, so you can also use one of their ready-made libraries instead of the code on this page.

Your signing secret​

Your account has one signing secret. It signs all your webhooks and all your delivery callbacks. Fetch it with Get signing secret:

curl https://api.hellosms.se/api/v1/account/signingSecret \
-u "API_USER:API_PASSWORD"

The answer holds the secret in signingSecret. It looks like whsec_ followed by a long text, for example whsec_aGVsbG9zbXMtZXhhbXBsZS1zZWNyZXQtbm90LXJlYWw=.

Keep the secret on your server, like a password. Anyone who has it can make calls that look like they come from HelloSMS. Don't put it in a web page, an app or a public repository.

The headers​

Each call carries three headers, in addition to Content-Type: application/json.

HeaderWhat it holds
webhook-idAn identifier for the message, starting with msg_. It is the same on every retry of the same call. Treat it as opaque: compare it and store it, don't take it apart.
webhook-timestampWhen this attempt was sent, as a UNIX timestamp in seconds. Every retry gets a new timestamp.
webhook-signatureOne or more v1, entries, separated by a space. Each entry is v1, followed by a base64 signature. You get more than one entry only while you are changing your secret, see Changing your secret.

Verify a call​

Do these steps in this order. If a step fails, answer with anything other than 200.

  1. Read the raw body. Take the request body exactly as it arrived, before any JSON parsing. The signature covers the exact bytes HelloSMS sent. A body you have parsed and written out again can differ in spacing or in the order of the fields, and then the check fails.
  2. Check the timestamp. Reject the call if webhook-timestamp is more than 5 minutes (300 seconds) away from your own clock. This stops someone from replaying an old call, and it also means your server clock has to be correct.
  3. Build the signed content. Join the three parts with a full stop: webhook-id, then webhook-timestamp, then the raw body. For example msg_….1672531260.{"apiMessageId":…}.
  4. Prepare the key. Remove the whsec_ at the start of your secret and decode the rest from base64. Those bytes are the key. Don't use the whsec_… text itself as the key.
  5. Calculate the signature. Take HMAC-SHA256 of the signed content with that key and encode the result as base64.
  6. Compare. Split webhook-signature on spaces. For each entry that starts with v1,, compare the part after the comma with your result. Use a constant-time comparison. The call is genuine if any one entry matches.
  7. Answer. Answer exactly 200 when you accept the call. Anything else, other 2xx answers and redirects included, counts as a failure and HelloSMS tries again after 1, 5, 15, 60 and 360 minutes. Each retry is signed again with a new timestamp, so a call that failed only because of a wrong secret can succeed later.
  8. Skip duplicates. HelloSMS can send the same call more than once, for example when your answer arrives late. Remember the webhook-id values you have handled, and if you see one again, answer 200 and do nothing more.

Changing your secret​

You can change the secret whenever you like, and you should if you suspect that someone else has seen it. Use Rotate signing secret:

curl -X POST https://api.hellosms.se/api/v1/account/rotateSigningSecret \
-u "API_USER:API_PASSWORD" \
-H "Content-Type: application/json" \
-d '{ "previousSecretValidForSeconds": 86400 }'

The new secret is current at once, and the answer holds it. The old secret keeps signing for previousSecretValidForSeconds seconds, 86400 (24 hours) if you leave it out, up to 604800 (7 days). While that overlap lasts, every call carries two signatures in webhook-signature, the new one first, and the answer shows when the overlap ends in previousSecretValidUntil. A receiver that knows either secret accepts the call, which is what lets you switch without dropping any:

  1. Call the rotate endpoint.
  2. Deploy the new secret to your receiver. During the overlap every call carries a signature for each secret, so a receiver that still has the old secret and one that already has the new secret both accept it.
  3. Done. The second entry disappears from webhook-signature at previousSecretValidUntil.

Only one old secret is kept. If you rotate again during an overlap, the earlier old secret stops signing at once.

If your secret has leaked, rotate with "previousSecretValidForSeconds": 0. The old secret then stops signing immediately, so whoever holds it can no longer make a call that passes your check. A rotate that comes less than a minute after the previous one changes nothing, even with 0, and the answer says Signing secret was rotated less than a minute ago; returning the current secret. If you get that answer after a leak, wait a minute and rotate again with 0.

You can look at the secret and at the end of a running overlap at any time with Get signing secret. previousSecretValidUntil is null when no old secret is signing.

A worked example​

Use this to test your own code. The secret is an example and not a real secret: the text hellosms-example-secret-not-real, shown as HelloSMS shows a secret.

Signing secretwhsec_aGVsbG9zbXMtZXhhbXBsZS1zZWNyZXQtbm90LXJlYWw=
webhook-idmsg_4f9c1e7a2b8d3065a1c4e9d2
webhook-timestamp1672531260

The body, on one line and with no line break at the end, exactly as it is sent:

{"apiMessageId":"12345","status":"delivered","timestamp":1672531199,"callbackRef":"someReference"}

The timestamp in the body is when the status changed. It is not the same thing as webhook-timestamp, which is when the call was sent.

The signed content is the three parts joined with full stops:

msg_4f9c1e7a2b8d3065a1c4e9d2.1672531260.{"apiMessageId":"12345","status":"delivered","timestamp":1672531199,"callbackRef":"someReference"}

Your code must produce exactly this webhook-signature value:

v1,JjBiSHQSrkc2Hrf4uSzINVBc7dKdbIHfqNfUas42sz8=

While you rotate, the header holds two entries separated by a space, for example this one where the second entry comes from the old secret whsec_aGVsbG9zbXMtZXhhbXBsZS1vbGQtc2VjcmV0LW5vcGU=:

v1,JjBiSHQSrkc2Hrf4uSzINVBc7dKdbIHfqNfUas42sz8= v1,vd+/X5CpOaM5ycCQW0eHcNnHGRBHxBDR0T3bOUtbcZs=

If your result differs, check the usual causes: the body was parsed and written out again, the key was the whole whsec_… text, or the three parts were joined with something other than full stops.

Code sample​

This Node.js function does steps 2 to 6 with only the built-in crypto module. Pass it the raw body, the headers (with lower-case names) and your secret. To accept both secrets during a rotation, pass an array.

const crypto = require("crypto");

function verifyHelloSmsCall(rawBody, headers, secrets, now = Math.floor(Date.now() / 1000)) {
const id = headers["webhook-id"];
const timestamp = headers["webhook-timestamp"];
const signatureHeader = headers["webhook-signature"];
if (!id || !timestamp || !signatureHeader) return false;

// Step 2: the call must be at most 5 minutes old
if (!/^\d+$/.test(timestamp) || Math.abs(now - Number(timestamp)) > 300) return false;

// Step 3: the signed content
const signedContent = `${id}.${timestamp}.${rawBody.toString("utf8")}`;

// Step 6: any "v1," entry may match
const received = signatureHeader
.split(" ")
.filter((entry) => entry.startsWith("v1,"))
.map((entry) => entry.slice(3));

return [].concat(secrets).some((secret) => {
// Step 4: the key is the decoded part after "whsec_"
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
// Step 5: HMAC-SHA256 of the signed content
const expected = crypto.createHmac("sha256", key).update(signedContent).digest();
return received.some((entry) => {
const given = Buffer.from(entry, "base64");
return given.length === expected.length && crypto.timingSafeEqual(given, expected);
});
});
}

In an Express route, get the raw body with express.raw({ type: "application/json" }) and answer 200 only when the check passes:

app.post("/hellosms", express.raw({ type: "application/json" }), (req, res) => {
if (!verifyHelloSmsCall(req.body, req.headers, process.env.HELLOSMS_SIGNING_SECRET)) {
return res.sendStatus(400);
}
// Skip the call if you have handled req.headers["webhook-id"] before, then process req.body
res.sendStatus(200);
});

The worked example is years old, so the timestamp check would reject it. To test with it, pass the example's timestamp as the current time:

verifyHelloSmsCall(
'{"apiMessageId":"12345","status":"delivered","timestamp":1672531199,"callbackRef":"someReference"}',
{
"webhook-id": "msg_4f9c1e7a2b8d3065a1c4e9d2",
"webhook-timestamp": "1672531260",
"webhook-signature": "v1,JjBiSHQSrkc2Hrf4uSzINVBc7dKdbIHfqNfUas42sz8=",
},
"whsec_aGVsbG9zbXMtZXhhbXBsZS1zZWNyZXQtbm90LXJlYWw=",
1672531260
); // true