Webhook payload signing

[NeoXTof]

Hello,

I've installed the latest relase version and I'm trying to figure out how the new "webhook payload signing" feature works. I've defined a signing key (ramdom 32 alphanumeric characters) but nothing changed in the info sent when webhooks are triggered.

Can you/someone explain me how to use it ?

Thanks in advance

[capcom6]

Hello!

The payload itself remains unchanged, but two new HTTP headers are now included in the request: X-Signature and X-Timestamp.

To verify the signature, you need to:

1. Concatenate the raw request payload with the value of the X-Timestamp header.
2. Calculate the HMAC-SHA256 hash of the resulting string using your signing key.
3. Compare the computed hash with the value of the X-Signature header. They should match.

Some examples are available at: https://docs.sms-gate.app/features/webhooks/#payload-signing

[NeoXTof]

Thanks a lot for your fast reply

[capcom6]

You're welcome!

[NeoXTof]

Sorry to bother you but I'm having a weird issue with signature. I'm made a function in my webhook to calculate it . With the sms:delivered event, it's working perfeclty. But when I'm trying to use it for sms:received, I'm always having a different signature than the one calculated by the phone. Is there anything different for the signature of a received sms ?

[capcom6]

The signing logic is the same for all webhook events. Ensure that you are using the raw request body and concatenating it with the X-Timestamp header value without adding any extra characters in between.

For example:

• Body:

  {"deviceId":"ffffffffceb0b1db00000193991c27e5","event":"sms:received","id":"-9qZ4oiiZZRm-h_A3mrp2","payload":{"message":"Android is always a sweet treat!","receivedAt":"2025-03-14T07:29:55.000+07:00","messageId":"69bde8d0","phoneNumber":"6505551212","simNumber":1},"webhookId":"LreFUt-Z3sSq0JufY9uWB"}

• X-Timestamp: 1741912196

After concatenation, the string to sign becomes:

{"deviceId":"ffffffffceb0b1db00000193991c27e5","event":"sms:received","id":"-9qZ4oiiZZRm-h_A3mrp2","payload":{"message":"Android is always a sweet treat!","receivedAt":"2025-03-14T07:29:55.000+07:00","messageId":"69bde8d0","phoneNumber":"6505551212","simNumber":1},"webhookId":"LreFUt-Z3sSq0JufY9uWB"}1741912196

Using the signing key fu3Y3yxW, the expected signature is:

5487b5d258923b0fe4bed3da9a03b351034e2443ef5d6c8e878094c5838e7c26

If you’re still encountering issues, double-check that:

1. The raw request body is being used exactly as received (no extra spaces, formatting, or modifications).
2. The X-Timestamp value is concatenated directly to the end of the raw body.
3. The signing key is correctly applied in the HMAC-SHA256 calculation.

[NeoXTof]

Thanks for the answer. I made some more test, it seems my issue is when passing the body as parameter from my webhook server to my hmac python function. It's somehow modified (probably the " and the space)

[NeoXTof]

I also noticed that the field in the payload of the webhook I receive are not in the same order than in your example. If I put the field in the same order than the example, my calculation of the signature is ok.

example of the body I receive (phone number has been edited for privacy)

{"deviceId":"00000000000ba0b60000019474be8d90","event":"sms:received","id":"x3MBB7cp2zdOs2eMrj6R-","payload":{"message":"Test","messageId":"9f7a8075","phoneNumber":"+336000000000","receivedAt":"2025-03-14T15:21:03.000+01:00","simNumber":1},"webhookId":"gotify-received"}

and in your example

{"deviceId":"ffffffffceb0b1db00000193991c27e5","event":"sms:received","id":"-9qZ4oiiZZRm-h_A3mrp2","payload":{"message":"Android is always a sweet treat!","receivedAt":"2025-03-14T07:29:55.000+07:00","messageId":"69bde8d0","phoneNumber":"6505551212","simNumber":1},"webhookId":"LreFUt-Z3sSq0JufY9uWB"}

The "receivedAt" attribute in my webhook payload is after the "phoneNumber" whereas in yours it's after the "message". I'm continuing my investigation to see if my webhook server is doing anything on the payload

[NeoXTof]

Solved it, it's my webhook server that is "sorting alphabatically" all the elements without any notice.