Class: Lithic::Resources::Webhooks

Inherits:
Object
  • Object
show all
Defined in:
lib/lithic/resources/webhooks.rb

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Webhooks

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Webhooks.

Parameters:



82
83
84
 
# File 'lib/lithic/resources/webhooks.rb', line 82

def initialize(client:)
  @client = client
end

Instance Method Details

#parse(payload, headers:, secret: nil) ⇒ Lithic::Models::AccountHolderCreatedWebhookEvent, ...

Parses and verifies a webhook payload. Verifies the signature before parsing.

Examples:

event = lithic.webhooks.parse(
  request.body.read,
  headers: request.headers
)

Parameters:

  • payload (String) —

    The raw webhook payload as a string

  • headers (Hash{String => String}) —

    The webhook request headers

  • secret (String, nil) (defaults to: nil) —

    The webhook secret. If not provided, reads from LITHIC_WEBHOOK_SECRET environment variable.

Returns:

Raises:

  • (ArgumentError) —

    if secret is not provided and LITHIC_WEBHOOK_SECRET env var is not set

  • (Lithic::Errors::MissingDependencyError) —

    if the standardwebhooks gem is not installed

  • (StandardWebhooks::WebhookVerificationError) —

    if the signature is invalid



23
24
25
26
 
# File 'lib/lithic/resources/webhooks.rb', line 23

def parse(payload, headers:, secret: nil)
  verified_json = verify_signature(payload: payload, headers: headers, secret: secret)
  Lithic::Internal::Type::Converter.coerce(Lithic::Models::ParsedWebhookEvent, verified_json)
end

#parse_unsafe(payload) ⇒ Lithic::Models::AccountHolderCreatedWebhookEvent, ...

Parses a webhook payload without verifying the signature.

WARNING: This method does not verify the webhook signature. Use only for testing or when signature verification is not required.

Parameters:

  • payload (String) —

    The raw webhook payload as a string

Returns:



36
37
38
39
 
# File 'lib/lithic/resources/webhooks.rb', line 36

def parse_unsafe(payload)
  parsed = JSON.parse(payload, symbolize_names: true)
  Lithic::Internal::Type::Converter.coerce(Lithic::Models::ParsedWebhookEvent, parsed)
end

#verify_signature(payload:, headers:, secret: nil) ⇒ Hash

Verifies the signature of a webhook payload using the Standard Webhooks specification.

Examples:

json = lithic.webhooks.verify_signature(
  payload: request.body.read,
  headers: request.headers
)
puts json[:event_type]

Parameters:

  • payload (String) —

    The raw webhook payload as a string

  • headers (Hash{String => String}) —

    The webhook request headers

  • secret (String, nil) (defaults to: nil) —

    The webhook secret (with or without the “whsec_” prefix). If not provided, reads from LITHIC_WEBHOOK_SECRET environment variable.

Returns:

  • (Hash) —

    The parsed webhook payload with symbolized keys

Raises:

  • (ArgumentError) —

    if secret is not provided and LITHIC_WEBHOOK_SECRET env var is not set

  • (Lithic::Errors::MissingDependencyError) —

    if the standardwebhooks gem is not installed

  • (StandardWebhooks::WebhookVerificationError) —

    if the signature is invalid



60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/lithic/resources/webhooks.rb', line 60

def verify_signature(payload:, headers:, secret: nil)
  secret ||= ENV["LITHIC_WEBHOOK_SECRET"]
  if secret.nil? || secret.empty?
    raise ArgumentError, "Webhook secret must be provided or set in LITHIC_WEBHOOK_SECRET environment variable"
  end

  begin
    require("standardwebhooks")
  rescue LoadError
    raise Lithic::Errors::MissingDependencyError.new(
      gem_name: "standardwebhooks",
      feature: "webhook signature verification"
    )
  end

  wh = StandardWebhooks::Webhook.new(secret)
  wh.verify(payload, headers)
end