Module: PaymentKit::Webhook

Defined in:
lib/payment_kit/webhook.rb

Overview

Webhook signature verification and event construction (Rails-free PORO).

PaymentKit delivers X-Webhook-Signature: sha256=<hex> over the raw body. Multiple signing secrets are tried in order, which is what the roll-secret grace period requires: during rotation both the old and new secret are live.

Class Method Summary collapse

Class Method Details

.construct_event(payload, signature, secrets) ⇒ Object

Verifies payload against signature using one or more secrets and returns the parsed JSON event as a Hash.

payload

raw request body String, never a re-serialised version

signature

X-Webhook-Signature header value

secrets

one signing secret String, or an Array of them

Raises AuthenticationError when no signing secret is configured, SignatureVerificationError when the signature is missing or does not verify, and InvalidRequestError when the verified payload is not JSON.

Raises:



25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/payment_kit/webhook.rb', line 25

def construct_event(payload, signature, secrets)
  secret_list = Array(secrets).flatten.compact.reject { |value| blank?(value) }
  raise AuthenticationError, "PaymentKit signing_secret is not configured" if secret_list.empty?

  raise SignatureVerificationError, "PaymentKit webhook signature is missing" if blank?(signature)

  verified = secret_list.any? { |secret| signature_valid?(payload, signature, secret) }
  raise SignatureVerificationError, "PaymentKit webhook signature verification failed" unless verified

  parse_payload(payload)
end