This guide covers URL-safe Base64 decoding for signed_request payload handling and explains a practical validation path that avoids common signature mistakes. It is a security-aware troubleshooting guide based on production maintenance of older integration flows where payload format looked valid but verification failed under edge-case input. We will cover payload split rules, URL-safe decoding conversion, signature checks, and safe failure behavior, with companion checks in reference checklists.

Why these payloads fail in real systems

The request value usually contains two segments separated by a dot:

  1. encoded signature
  2. encoded payload JSON

Developers often decode one piece correctly and still fail verification because of URL-safe alphabet conversion or padding assumptions.

For Base64 behavior details, MDN has a clear reference section at developer.mozilla.org.

Step 1: Split the payload safely

1
2
encoded_sig, encoded_payload = signed_request.to_s.split('.', 2)
raise 'invalid signed_request format' unless encoded_sig && encoded_payload

Reject malformed values immediately.

Step 2: Convert URL-safe Base64 to standard form

1
2
3
4
def urlsafe_base64_decode(str)
  str += '=' * ((4 - str.length % 4) % 4)
  Base64.decode64(str.tr('-_', '+/'))
end

The - and _ substitutions plus optional padding are the critical details.

Step 3: Verify signature before trusting payload

1
2
3
4
sig = urlsafe_base64_decode(encoded_sig)
payload_raw = urlsafe_base64_decode(encoded_payload)
expected = OpenSSL::HMAC.digest('sha256', app_secret, encoded_payload)
raise 'invalid signature' unless Rack::Utils.secure_compare(sig, expected)

Only parse JSON after signature verification passes.

Step 4: Parse payload and validate claims

Check expected fields and expiration values. Do not trust optional attributes by default.

Caution

Fail closed. If parsing or signature verification fails, reject request and log structured diagnostics without leaking secrets.

FAQ

Why not decode with plain Base64.decode64 directly?

URL-safe variants need alphabet conversion and optional padding normalization first.

Should I still support this flow in new builds?

Use current provider guidance for new integrations. Keep this only where existing traffic requires it.

What should be logged?

Timestamp, request id, failure type, and high-level reason. Avoid logging raw payload secrets.

Filed under