Uri Hooks
URI Hooks are a library that given a URI (http/https, mailto, tel, sms, etc) will figure out the best way of calling that URI or schema. The schema is automatically identified from the URI (in addition to the service). Currently the following schema and services are supported:
- email - (
mail:
,mailto:
,email:
- Sends an email to the address in the uri). - CircleCI - Kicks off a circleci job
- Slack - Sends a message to a slack channel.
- Opsgenie - Fires an alert in ops genie.
- Microsoft Teams - Sends a message to a microsoft teams channel.
- Rollbar - Fires a new error in rollbar.
- http/https - Sends a HTTPS
POST
message.
Usage
Hooks Object
handler = hooks.find(uri string)
Return the first hook handler that can manage the specified URI, otherwise return null.
result = hooks.fire(id string|number, uri string, type string, incoming object[, hmac string, headers string, token string])
Fire a hook.
-
id
- The identifier for this webhook, can be anything, its used to identify the hook in debug logs only (the uri is not printed for security reasons). -
uri
- The URI for this hook. -
type
- The type of event being fired as a string. This is interpretted and used differently by different handlers. Should be an alpha numeric identifier. -
incoming
- A JSON object of the payload to send. For systems that don't accept JSON objects the object is generally serialized and pretty printed into a string. -
hmac
- For HTTP/HTTPS payloads the SHA1 hmac to added to the headerx-akkeris-signature: sha1=...
if the payload must be validated using a signature. This is optional. -
headers
- Headers to include (for http/https headers to the request, for email headers to the smtp system). This is optional. -
token
- A token to send as part of the payload. For http/https this becomes the headerx-akkeris-token: ...
. This is optional
handlers[] = hooks.hooks
Get all known hooks (even if some cannot be used).
handlers[] = hooks.available()
Get all available hooks (only those that can be used).
Handler Object
-
handler.fire
- same signature ashooks.fire
above. -
handler.test(uri)
- returns a true or false if the handler can fire a hook for the uri specified. -
handler.enabled()
- returns whether or not the handler is allowed to fire. -
handler.name
- A string human readable name -
handler.description
- A human readable description of the hook -
handler.format
- An example human readable format of the hook -
handler.image
- A string containing a data uri with an icon (PNG transparent) of the handler. -
obj = handler.formatter(incoming)
- The default formatter for the hook (modifies the incoming payload to the payload dested). Can be set to override default formatting.
Result Object
{
"sent_metadata":{},
"sent_data":{},
"received_code":200,
"received_metadata":{},
"received_data":{},
}
Special Incoming Formats
For email you can specify a text, html and subject by adding the respective fields to the incoming object passed.
Environment Variables
-
SMTP
- Should be smtps://mail.example.com or smtp://mail.example.com:25 (if a username/password is added it will use it as authentication) -
SMTP_FROM
- The email address to send from. -
SMTP_HTML_TEMPLATE_[type]
- Set the HTML format to use where[type]
is the type event name passed intohooks.fire
. Use{field}
to represent a value in theincoming
object passed intohooks.fire
. -
WEBHOOK_DISABLE_[handler]
- Set to true to disallow any handler from being used. E.g., WEBHOOK_DISABLE_EMAIL=true to disable sending emails.
Example
const hooks = require('urihooks');
hooks.fire(1, 'mailto:john.smith@example.com', 'some-event-name', {"html":"<b>Hello!</b>", "subject":"Oh hello", "text":"Hello"});