escape_unicode() corrupts payload during webhook validation in validate_message()

[ajvoisancountyofsb]

• I have checked that the SDK documentation doesn't solve my issue.
• I have checked that the API documentation doesn't solve my issue.
• I have searched the Box Developer Forums and my issue isn't already reported (or if it has been reported, I have attached a link to it, for reference).
• I have searched Issues in this repo and my issue isn't already reported.

Description of the Issue

The escape_unicode() function used internally by WebhooksManager.validate_message() alters the raw webhook payload, resulting in failed validation for otherwise valid Box webhook events. validate_message() calls internal.utils.compute_webhook_signature() which then passes the request body to internal.utils.escape_unicode().

The function escapes:

• Control characters (\n, \r, \t)

• All non-ASCII characters

• Supplementary Plane Unicode characters via surrogate pairs

Since the Box signature is computed over the raw request body, escaping any characters changes the payload and causes a signature mismatch.

Successful workarounds:

1. Removing the internal call to escape_unicode()

2. Manual signature validation following the method described at https://developer.box.com/guides/webhooks/v2/signatures-v2/#manual-signature-verification

Steps to Reproduce

1. Attempt to validate a webhook payload that contains any of the escaped characters above using WebhooksManager.validate_message()

Expected Behavior

validate_message() should use the exact raw bytes of the webhook payload — without transformations — to compute the HMAC.

Versions Used

Python SDK: box-sdk-gen==1.12.0
Python: 3.11.4

[arjankowski]

Hello @ajvoisancountyofsb,

You're right, the issue seems to come from escape_unicode() unnecessarily escaping backslashes \, which alters the raw payload and breaks signature validation.

Can you just confirm please that the payload you are validating has the \ character in it?

Regards,
Artur

[ajvoisancountyofsb]

Hi!

Thank you for looking into this.

I can confirm that the payload contains the \ character.

Thanks,
AJ

[mwwoda]

Hello,

We identified issues when escaping forward (/) and back (\) slashes. I'm currently looking how we can fix this. Did you also encounter issues with other special characters like newline?

[mwwoda]

I introduced the fix in #603. Are you able to verify that it resolves your issue?

[ajvoisancountyofsb]

Hi,

Unfortunately the fix has not resolved the issue. After some testing it appears the offending line in the fixed escape_unicode() is temp = re.sub(r'\\(?!/)', r'\\\\', value). Bypassing that line successfully verifies the signature.

The \ character is still replaced by \\ leading to the following:
{\"scope\":\"gcm\"} becomes {\\"scope\\":\\"gcm\\"}

This payload is being used as-is in AWS API Gateway and Lambda. I originally believed API Gateway was mutating the payload but the manual signature verification is still successful.

[mwwoda]

Hi,

It seems that that this issue could be more complex to solve, and we want to do this in a way that does not impact existing clients of this function if possible.

I have a few followup questions from my side that could help us solve this:

1. Just to confirm, do bypassing call toescape_unicode function fixes your issue?
2. Can you provide a way to reproduce such webhook payload. I'm mostly interested in setup on Box side. Sample payload could also be handy. If you can provide one make sure it does not include any sensitive information)

[ajvoisancountyofsb]

Hi, I totally understand.

1. I can confirm that bypassing the call to escape_unicode fixes my issue.
2. Here is a redacted payload body that is being sent from Box Custom Skills to AWS API Gateway (HTTP API) and then Lambda. The custom skill is triggered on PDF file upload.

"body": '{"id":"redacted_id","type":"skill_invocation","created_at":"2025-06-02T14:24:38-07:00","trigger":"SKILL_APP_TEST_EVENT","enterprise":{"type":"enterprise","id":"redacted_id","name":"redacted_name"},"source":{"id":0000000000000,"type":"file","file_version":{"id":0000000000000},"name":"redacted_name","owner_enterprise_id":0000000000,"parent":{"id":0},"sequence_id":0,"size":00000},"event":{"event_id":"000000000","created_at":"2025-06-02T14:24:38-07:00","created_by":{"type":"user","id":00000000000,"name":"","login":"redacted_email"},"source":{"id":0000000000000,"type":"file","file_version":{"id":0000000000000},"name":"redacted_name","owner_enterprise_id":0000000000,"parent":{"id":0},"sequence_id":0,"size":00000}},"parameters":{},"skill":{"api_key":"redacted_key","id":0000000,"name":"redacted_name","type":"skill"},"token":{"read":{"access_token":"redacted_access_token","expires_in":1748985878,"restricted_to":"[{\\"scope\\":\\"gcm\\"},{\\"scope\\":\\"item_read\\",\\"object_id\\":0000000000000,\\"object_type\\":\\"file\\"},{\\"scope\\":\\"ai.readwrite\\",\\"object_id\\":0000000000000,\\"object_type\\":\\"file\\"}]","token_type":"bearer"},"write":{"access_token":"redacted_access_token","expires_in":1748985878,"restricted_to":"[{\\"scope\\":\\"gcm\\"},{\\"scope\\":\\"item_upload\\",\\"object_id\\":0000000000000,\\"object_type\\":\\"file\\"},{\\"scope\\":\\"manage_skill_invocations\\"}]","token_type":"bearer"}},"status":{"state":"invoked","message":"","error_code":"","additional_info":""},"skill_rules":null}'