Module: Rerout::Webhooks

Defined in:
lib/rerout/webhooks.rb

Overview

Webhook signature verification.

Rerout signs every webhook delivery with an ‘X-Rerout-Signature` header shaped as `t=unix_seconds,v1=hex_hmac_sha256`. The HMAC is computed over `“timestamp.raw_body”` with the endpoint signing secret (`whsec_…`) as the key.

Examples:

Rack / Rails controller

raw = request.body.read
ok = Rerout::Webhooks.verify_signature(
  raw_body: raw,
  signature_header: request.headers['X-Rerout-Signature'],
  secret: ENV.fetch('REROUT_WEBHOOK_SECRET')
)
head(:unauthorized) and return unless ok

Constant Summary collapse

DEFAULT_TOLERANCE_SECONDS =

Default tolerance window in seconds between the ‘t=` timestamp and the current time. Five minutes — protects against captured-replay attacks.

300

Class Method Summary collapse

Class Method Details

.verify_signature(raw_body:, signature_header:, secret:, tolerance_seconds: DEFAULT_TOLERANCE_SECONDS, now: nil) ⇒ Boolean

Verify a Rerout webhook signature.

Returns ‘true` only when the header parses cleanly, the timestamp is within `tolerance_seconds` of `now`, and the computed HMAC matches the supplied `v1` in constant time. Returns `false` for every failure mode —it never raises.

Parameters:

  • raw_body (String) —

    the exact, unmodified request body bytes.

  • signature_header (String) —

    value of the ‘X-Rerout-Signature` header.

  • secret (String) —

    the endpoint signing secret (‘whsec_…`).

  • tolerance_seconds (Integer) (defaults to: DEFAULT_TOLERANCE_SECONDS) —

    staleness window. ‘0` disables the timestamp check entirely. Defaults to 300.

  • now (Proc, #call, nil) (defaults to: nil) —

    injectable clock returning the current unix time in seconds. Defaults to ‘Time.now.to_i`. Useful for tests.

Returns:

  • (Boolean) 


41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/rerout/webhooks.rb', line 41

def self.verify_signature(raw_body:, signature_header:, secret:,
                          tolerance_seconds: DEFAULT_TOLERANCE_SECONDS,
                          now: nil)
  return false if raw_body.nil?
  return false if signature_header.nil? || signature_header.to_s.empty?
  return false if secret.nil? || secret.to_s.empty?

  parsed = parse_header(signature_header.to_s)
  return false if parsed.nil?

  timestamp, v1 = parsed
  return false unless within_tolerance?(timestamp, tolerance_seconds, now)

  expected = OpenSSL::HMAC.hexdigest('SHA256', secret.to_s, "#{timestamp}.#{raw_body}")
  secure_compare(expected, v1)
end