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

1. handler = hooks.find(uri string)

Return the first hook handler that can manage the specified URI, otherwise return null.

2. 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 header x-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 header x-akkeris-token: .... This is optional

3. handlers[] = hooks.hooks

Get all known hooks (even if some cannot be used).

4. handlers[] = hooks.available()

Get all available hooks (only those that can be used).

Handler Object

1. handler.fire - same signature as hooks.fire above.
2. handler.test(uri) - returns a true or false if the handler can fire a hook for the uri specified.
3. handler.enabled() - returns whether or not the handler is allowed to fire.
4. handler.name - A string human readable name
5. handler.description - A human readable description of the hook
6. handler.format - An example human readable format of the hook
7. handler.image - A string containing a data uri with an icon (PNG transparent) of the handler.
8. 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 into hooks.fire. Use {field} to represent a value in the incoming object passed into hooks.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:[email protected]', 'some-event-name', {"html":"<b>Hello!</b>", "subject":"Oh hello", "text":"Hello"});