Add docstring, break out signature version

Author: paul-griffith

slack/web/base_client.py

@@ -21,6 +21,7 @@
 
 class BaseClient:
     BASE_URL = "https://www.slack.com/api/"
+    SIGNATURE_VERSION = "v0"
 
     def __init__(
         self,
@@ -237,7 +238,30 @@ def _get_user_agent():
     def validate_slack_signature(
         *, signing_secret: str, data: str, timestamp: str, signature: str
     ) -> bool:
-        format_req = str.encode(f"v0:{timestamp}:{data}")
+        """
+        Slack creates a unique string for your app and shares it with you. Verify
+        requests from Slack with confidence by verifying signatures using your
+        signing secret.
+
+        On each HTTP request that Slack sends, we add an X-Slack-Signature HTTP
+        header. The signature is created by combining the signing secret with the
+        body of the request we're sending using a standard HMAC-SHA256 keyed hash.
+
+        https://api.slack.com/docs/verifying-requests-from-slack#how_to_make_a_request_signature_in_4_easy_steps__an_overview
+
+        Args:
+            signing_secret: Your application's signing secret, available in the
+                Slack API dashboard
+            data: The raw body of the incoming request - no headers, just the body.
+            timestamp: from the 'X-Slack-Request-Timestamp' header
+            signature: from the 'X-Slack-Signature' header - the calculated signature
+                should match this.
+
+        Returns:
+            True if signatures matches
+        """
+        format_req = str.encode(f"{BaseClient.SIGNATURE_VERSION}:{timestamp}:{data}")
         encoded_secret = str.encode(signing_secret)
         request_hash = hmac.new(encoded_secret, format_req, hashlib.sha256).hexdigest()
-        return hmac.compare_digest(f"v0={request_hash}", signature)
+        calculated_signature = f"{BaseClient.SIGNATURE_VERSION}={request_hash}"
+        return hmac.compare_digest(calculated_signature, signature)