WebhooksEmitter

Emits your events as outgoing http webhooks.

WebhooksEmitter takes care of emitting your events with an HTTP POST to remote listeners. Tries to be non-blocking as much as possible, by queuing events even during the HTTP operation or backoff intervals. Handles retries and timeouts for you. Is capable to digital sign the payload, with a configurable secret, in order to check the message integrity on the receiver side.

Installation

The package can be installed by adding webhooks_emitter to your list of dependencies in mix.exs:

def deps do
  [
    {:webhooks_emitter, "~> 0.2"}
  ]
end

Usage

To start, a new configuration must be built using WebhooksEmitter.Config.new/1:

iex> config = WebhooksEmitter.Config.new("https://your.end.point")

Then attach a new handler for the above config, using WebhooksEmitter.attach/3 to some event:

iex> :ok = WebhooksEmitter.attach(:my_emitter, :some_event, config)

if the emitter id is already used, an error is returned:

iex> {:error, :already_exists} = WebhooksEmitter.attach(:already_used_id, :some_event, config)

Is possible to attach the same config to a list of events, using WebhooksEmitter.attach_many/3.

When your event is ready for dispatch, just call WebhooksEmitter.emit/3, with the payload and an optional request id, that will be added to the http request headers:

iex> {ok, request_id} = WebhooksEmitter.emit(:some_event, %{data: "foobar"}, "an_optional_request_id")

if the above request id is not passed, a new one will be automatically generated.

To detach an emitter, just call WebhooksEmitter.detach/1 with your attached emitter id:

iex> :ok = WebhooksEmitter.detach(:my_emitter)

Anatomy of an HTTP request performed by the emitter:

POST /hooks/ah7Ahtet6abohbai HTTP/1.1
Host: localhost:1234
X-Webhooks-Event: averyimportantevent
X-Webhooks-Delivery: fbc7fbe7-2e9b-4911-a50f-e0452672192c
X-Webhooks-Signature: sha256:2vu2rb2moi6dihmlm6tvd3nbdnahjncmus9p8pl76h3v4ub054h0
User-Agent: WebHooks-Emitter/0.1.2
Content-Type: application/json
Content-Length: 6615

{
  "message": "thank you for all the fish",
  ...
}

For more information, see the documentation.

License

Copyright 2020 Matteo Brancaleoni and VoiSmart S.R.L.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.