Hello HubSpot Team,
After spending several days troubleshooting webhook authentication failures, I discovered a critical point that is missing or unclear in the current V3 signature validation documentation, especially for PHP developers.
Main Issue
The documentation does not clarify that the URI used for the signature generation must match the full Target URL as configured in HubSpot, including the protocol and domain (for example: https://example.com/wp-json/…).
Many developers assume it refers only to the URI path (like $_SERVER[‘REQUEST_URI’]), which leads to failed verification even if the rest of the process is correct.
Suggested Improvements
- Clearly mention that the full URL should be used when constructing the string for signature validation.
- Consider referencing this detailed PHP example which includes timestamp checking, URI decoding, and secure signature comparison:
PHP Example for V3 Signature Validation with full explanation
This might save other developers hours or even days of debugging and improve the experience for the PHP community.
Let me know if you’d like the code incorporated directly into the official documentation. I’d be happy to help.
Related Docs Page (suggested update spot):