docs(webhook): clarify Rails ActionController::Parameters needs to_unsafe_h

Author: svyatov

README.md

@@ -286,16 +286,23 @@ In your webhook handler, verify the signature, parse the payload, and
 acknowledge it by replying with the string `"100"`:
 
 ```ruby
+# In Rails, params[:data] is ActionController::Parameters, not a Hash — convert
+# it with .to_unsafe_h first, or the numeric-key ordering the signature depends
+# on is skipped and the check below rejects the payload. The payload is
+# signature-verified, so to_unsafe_h is safe here (.to_h would drop keys).
+# In bare Rack params["data"] is already a Hash; pass it as-is.
+data = params[:data].to_unsafe_h
+
 # Reject forged callbacks: SMS.ru signs every payload with your api_id.
 # The check is constant-time (timing-attack safe).
-unless SmsRu::Webhook.valid?(params["data"], params["hash"], "YOUR_API_ID")
+unless SmsRu::Webhook.valid?(data, params[:hash], "YOUR_API_ID")
   return head(:forbidden)
 end
 
 # SMS.ru sends up to 100 records as POST fields data[0]..data[N]
-# (a Hash in Rack/Rails, an Array in PHP). #parse handles either shape and
+# (a Hash in Rack, an Array in PHP). #parse handles either shape and
 # returns a typed event per record.
-SmsRu::Webhook.parse(params["data"]).each do |event|
+SmsRu::Webhook.parse(data).each do |event|
   case event
   when SmsRu::Events::SmsStatus        # delivery report
     # event.id, event.status_code, event.created_at; event.delivered? => 103

lib/sms_ru/webhook.rb

@@ -3,15 +3,23 @@
 class SmsRu
   # Parses the inbound webhook payload SMS.ru POSTs to your callback URL and
   # verifies its signature. SMS.ru sends the records as POST fields
-  # `data[0]..data[N]` (so `params["data"]` is a Hash in Rack/Rails, an Array
-  # in PHP) plus a `hash` field; acknowledge the webhook by replying with "100".
+  # `data[0]..data[N]` plus a `hash` field; acknowledge the webhook by replying
+  # with "100".
+  #
+  # The `data` param arrives as a Hash in bare Rack and an Array in PHP-style
+  # clients. In Rails it is an `ActionController::Parameters`, which is **not** a
+  # Hash — convert it with `.to_unsafe_h` first, or the numeric-key ordering the
+  # signature depends on is skipped and {valid?} rejects the payload. The
+  # payload is signature-verified, so `to_unsafe_h` is safe here (`.to_h` would
+  # drop unpermitted keys).
   #
   # {parse} returns one typed event per record — a {SmsRu::Events::SmsStatus},
   # {SmsRu::Events::CallcheckStatus}, {SmsRu::Events::Test}, or
   # {SmsRu::Events::Unknown} — best handled with a case match:
   #
-  #   return head(:forbidden) unless SmsRu::Webhook.valid?(params["data"], params["hash"], api_id)
-  #   SmsRu::Webhook.parse(params["data"]).each do |event|
+  #   data = params[:data].to_unsafe_h # Rails; pass params["data"] as-is in bare Rack
+  #   return head(:forbidden) unless SmsRu::Webhook.valid?(data, params[:hash], api_id)
+  #   SmsRu::Webhook.parse(data).each do |event|
   #     case event
   #     when SmsRu::Events::SmsStatus       then update_delivery(event.id, event.status_code)
   #     when SmsRu::Events::CallcheckStatus then confirm(event.id) if event.confirmed?