# ExTwilioWebhook

ExTwilioWebhook is a simple library that validates Twilio webhooks in Plug applications.
It has been developed for internal use at virtualQ GmbH, but it may come in handy for
someone else.

## Installation

Add `:ex_twilio_webhook` to project dependencies in `mix.exs`.

def deps do
    {:ex_twilio_webhook, github: "moroz/ex_twilio_webhook"}

In order to validate a webhook, the library needs access to both the parsed params
and to the unprocessed raw body of the request. However, by default, `Plug.Parsers`
discards the raw body when it parses the params. If your application is using Phoenix,
modify the call to `Plug.Parsers` in your application's endpoint module to add the `:body_reader` option:

plug Plug.Parsers,
  parsers: [:urlencoded, :json],
  pass: ["*/*"],
  json_decoder: Phoenix.json_library(),
  body_reader: {ExTwilioWebhook.BodyReader, :read_body, []}

Add the `ExTwilioWebhook.Plug` to the endpoint after `Plug.Parsers`:

plug ExTwilioWebhook.Plug,
  at: ~r"^/twilio/",
  secret: fn account_sid ->
  public_host: {System, :get_env, ["PUBLIC_HOST"]}

Configuration options:

- `at`: the request path at which the plug will validate webhook signatures.
  When given a string, it will only match if the `request_path`
  is equal to the pattern. When given a regular expression, it will match if
  the regular expression matches the `request_path`.

- `secret`: Twilio secret. The secret can be provided as a string, an `{m, f, a}`
  tuple, or an anonymous function of arity 0 or 1. When given a 1-arity function,
  the function will be called with the value of the `AccountSid` of each request.
  This is useful if your application needs to process webhooks from multiple
  Twilo accounts. When given an `{m, f, a}` tuple, the tuple will be called
  at runtime for each request.

- `public_host`: The public URL of your application with scheme, e. g.:
  ``. Can be provided as string or `{m, f, a}` tuple.
  When given a tuple, the tuple will be called at runtime for each request.