Class: Webhukhs::BaseHandler

Inherits:
Object
  • Object
show all
Defined in:
lib/webhukhs/base_handler.rb

Overview

Base class for webhook handlers.

Instance Method Summary collapse

Instance Method Details

#active? ⇒ Boolean

Tells the controller whether this handler is active or not. This can be used to deactivate a particular handler via feature flags for example, or use other logic to determine whether the handler may be used to create new received webhooks in the system. This is primarily needed for load shedding.

Returns:

  • (Boolean) 


99
100
101
 
# File 'lib/webhukhs/base_handler.rb', line 99

def active?
  true
end

#enqueue(webhook) ⇒ void

This method returns an undefined value.

Enqueues the processing job to process webhook asynchronously. The job class could be configured.

Parameters:



30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/webhukhs/base_handler.rb', line 30

def enqueue(webhook)
  # The configured job class can be a class name or a module, to support lazy loading
  job_class_or_module_name = Webhukhs.configuration.processing_job_class
  job_class = if job_class_or_module_name.respond_to?(:perform_later)
    job_class_or_module_name
  else
    job_class_or_module_name.constantize
  end

  job_class.perform_later(webhook)
end

#expose_errors_to_sender? ⇒ Boolean

Webhook senders have varying retry behaviors, and often you want to “pretend” everything is fine even though there is an error so that they keep sending you data and do not disable your endpoint forcibly. We allow this to be configured on a per-handler basis - a better webhooks sender will be able to make out some sense of the errors.

Returns:

  • (Boolean) 


89
90
91
 
# File 'lib/webhukhs/base_handler.rb', line 89

def expose_errors_to_sender?
  true
end

#extract_event_id_from_request(action_dispatch_request) ⇒ String

Default implementation just generates a random UUID, but if the webhook sender sends us an event ID we use it for deduplication. A duplicate webhook is not going to be stored in the database if it is already present there.

Parameters:

  • action_dispatch_request (ActionDispatch::Request) —

    request used to derive a stable event identifier

Returns:

  • (String) 


78
79
80
 
# File 'lib/webhukhs/base_handler.rb', line 78

def extract_event_id_from_request(action_dispatch_request)
  SecureRandom.uuid
end

#handle(action_dispatch_request) ⇒ void

This method returns an undefined value.

‘handle` accepts the ActionDispatch HTTP request and saves the webhook for later processing. It then enqueues an ActiveJob which will perform the processing using `process`.

Parameters:

  • action_dispatch_request (ActionDispatch::Request) —

    request from the controller



14
15
16
17
18
19
20
21
22
23
24
 
# File 'lib/webhukhs/base_handler.rb', line 14

def handle(action_dispatch_request)
  handler_module_name = self.class.name
  handler_event_id = extract_event_id_from_request(action_dispatch_request)

  webhook = ReceivedWebhook.new(request: action_dispatch_request, handler_event_id: handler_event_id, handler_module_name: handler_module_name)
  webhook.save!

  enqueue(webhook)
rescue ActiveRecord::RecordNotUnique # Webhook deduplicated
  Rails.logger.info { "#{inspect} Webhook #{handler_event_id} is a duplicate delivery and will not be stored." }
end

#process(received_webhook) ⇒ void

This method returns an undefined value.

This is the heart of your webhook processing. Override this method and define your processing inside of it. The ‘received_webhook` will provide access to the `ReceivedWebhook` model, which contains the received body of the webhook request, but also the full (as-full-as-possible) clone of the original ActionDispatch::Request that you can use.

Parameters:



49
50
 
# File 'lib/webhukhs/base_handler.rb', line 49

def process(received_webhook)
end

#valid?(action_dispatch_request) ⇒ Boolean

This method verifies that request is not malformed and actually comes from the webhook sender: signature validation, HTTP authentication, IP whitelisting and the like. There is a difference depending on whether you validate sync (in the receiving controller) or async (in the processing job): Validation is async - it takes place in the background job that gets enqueued to process the webhook. The ‘action_dispatch_request` will be reconstructed from the `ReceivedWebhook` data. Background validation is used because the most common misconfiguration that may occur is usually forgetting or misidentifying the signature for signed webhooks. If such a misconfiguration has taken place, the background validation (instead of rejecting the webhook at input) permits you to still process the webhook once the secrets have been configured correctly.

If this method returns ‘false`, the webhook will be marked as `failed_validation` in the database. If this method returns `true`, the `process` method of the handler is going to be called.

Parameters:

  • action_dispatch_request (ActionDispatch::Request) —

    reconstructed request from the stored webhook

Returns:

  • (Boolean)

See Also:



68
69
70
 
# File 'lib/webhukhs/base_handler.rb', line 68

def valid?(action_dispatch_request)
  true
end