Hookshot

Hookshot is a rubygem for submitting jobs to the Hookshot webhook delivery engine.

Installation

Hookshot is on rubygems, just add the latest version to your gemfile. Setup of the hookshot server is separate and more complex, so go read about that first.

Usage

Initialize a connection

require 'hookshot'
require 'redis'
hookshot = Hookshot.new(Redis.new(port: 6379, host: 'localhost'))

Enqueue a webhook

hookshot.enqueue(
  url: 'http://localhost:8080/post',
  headers: {"X-My-Header" => "value"},
  context: "42",
  payload: "request body")

Enqueue a webhook with a delay

You can enqueue a job but have it activate only after a specified delay.

hookshot.enqueue_in(60, # seconds
  url: 'http://localhost:8080/post',
  headers: {"X-My-Header" => "value"},
  context: "42",
  payload: "request body")

Read back failed jobs

Jobs that fail many times in a row are returned back to the application. Specifically, the context value passed in via the enqueue* methods is returned.

get_next_failure returns two values: the number of failures so far for this job, and the context passed in with the job. If nfailures is equal to Hookshot::FINAL_FAILURE, the job will not be retried. However, if nfailures is any other value, the job will still be retried; this is just an advisory because the job has been failing for at least 24 hours.

loop {
  nfailures, context = hookshot.get_next_failure
  if nfailures == Hookshot::FINAL_FAILURE
    delete_webhook_subscription(context)
  end
}

Check queue stats

Hookshot writes a lot of statistics to statsd/datadog, but to quickly check the current queue sizes, use queue_stats.

hookshot.queue_stats
# => { pending: 42, delayed: 42, failures: 42 }

Blacklist and Whitelist

Hookshot provides a manual blacklist and a manual whitelist:

  • Jobs for any domain in the blacklist are automatically rejected by hookshot.
  • Throttles for any domain in the whitelist are automatically allocated the maximum allowed throughput.

The format of the domain should be the full domain. The port should not be included if it is 80 or 443.

Examples:

URL Domain
http://example.com/post example.com
https://example.com/post example.com
http://example.com:8000 example.com:8000
http://example.com:80 example.com

Check the lists

hookshot.blacklist
#=> ["example.com"]
hookshot.whitelist
#=> ["google.com", "shopify.com"]

Add an item to the list

hookshot.blacklist!("example.com")
hookshot.whitelist!("google.com")

Remove an item from the list

hookshot.remove_blacklist("example.com")
hookshot.remove_whitelist("google.com")
```