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")
```