From 758757b1ed84d02c93197d53571d51a698ff3174 Mon Sep 17 00:00:00 2001
From: manisha1997 <singhmanisha.250025@gmail.com>
Date: Thu, 18 Sep 2025 15:21:51 +0530
Subject: [PATCH] chore: Add docs

---
 src/Twilio/Security/RequestValidator.cs | 33 ++++++++++++++++++-------
 1 file changed, 24 insertions(+), 9 deletions(-)

diff --git a/src/Twilio/Security/RequestValidator.cs b/src/Twilio/Security/RequestValidator.cs
index 8a1dcca1c..6a7d0157a 100644
--- a/src/Twilio/Security/RequestValidator.cs
+++ b/src/Twilio/Security/RequestValidator.cs
@@ -25,11 +25,15 @@ public RequestValidator(string secret)
         }
 
         /// <summary>
-        /// Validate against a request
+        /// Validate against a request.
+        /// The validate function is provided to validate incoming webhook requests from Twilio.
+        /// It does this by comparing the expected signature passed in with a signature it generates itself.
+        /// The signature is generated by creating an HMAC-SHA1 hash using the signing secret as the key,
+        /// and the full URL (including query string parameters and bodySHA256) as the message.
         /// </summary>
-        /// <param name="url">Request URL</param>
-        /// <param name="parameters">Request parameters</param>
-        /// <param name="expected">Expected result</param>
+        /// <param name="url">Request URL - This URL should include all query parameters and bodySHA256</param>
+        /// <param name="parameters">Request parameters. This includes any body that is part of the request.</param>
+        /// <param name="expected">Every Twilio Request has an x-twilio-signature associated with it. This is the expected twilio signature against which the generated signature is compared with.</param>
         /// <returns>true if the signature matches the result; false otherwise</returns>
         public bool Validate(string url, NameValueCollection parameters, string expected)
         {
@@ -37,11 +41,15 @@ public bool Validate(string url, NameValueCollection parameters, string expected
         }
 
         /// <summary>
-        /// Validate against a request
+        /// Validate against a request.
+        /// The validate function is provided to validate incoming webhook requests from Twilio.
+        /// It does this by comparing the expected signature passed in with a signature it generates itself.
+        /// The signature is generated by creating an HMAC-SHA1 hash using the signing secret as the key,
+        /// and the full URL (including query string parameters and bodySHA256) as the message.
         /// </summary>
-        /// <param name="url">Request URL</param>
-        /// <param name="parameters">Request parameters</param>
-        /// <param name="expected">Expected result</param>
+        /// <param name="url">Request URL - This URL should include all query parameters and bodySHA256</param>
+        /// <param name="parameters">Request parameters. This includes any body that is part of the request.</param>
+        /// <param name="expected">Every Twilio Request has an x-twilio-signature associated with it. This is the expected twilio signature against which the generated signature is compared with.</param>
         /// <returns>true if the signature matches the result; false otherwise</returns>
         public bool Validate(string url, IDictionary<string, string> parameters, string expected)
         {
@@ -125,6 +133,13 @@ public bool Validate(string url, string body, string expected)
             return Validate(url, (IDictionary<string, string>)null, expected) && ValidateBody(body, bodyHash);
         }
 
+        /// <summary>
+        /// Validate the body of a request.
+        /// The validateBody function is provided to validate the body of incoming webhook requests from Twilio
+        /// It does this by creating a SHA256 hash of the body and comparing it to the expected hash.
+        /// </summary>
+        /// <param name="rawBody">Raw body of the request</param>
+        /// <param name="expected">The expected SHA256 hash of the body</param>
         public static bool ValidateBody(string rawBody, string expected)
         {
 #if NET6_0_OR_GREATER
@@ -230,4 +245,4 @@ private static string PreserveCase(string url, string replacementString)
             return url.Substring(startIndex, replacementString.Length);
         }
     }
-}
\ No newline at end of file
+}