Nadia.Webhook (nadia v1.4.0)

Framework-neutral helpers for receiving Telegram webhook updates.

Nadia does not require Plug or Phoenix. Web frameworks can pass the raw request body and request headers to this module, then translate the result into the framework's response type.

Nadia.Webhook.dispatch_body(
  raw_body,
  MyApp.Bot,
  headers: request_headers,
  secret_token: System.fetch_env!("TELEGRAM_WEBHOOK_SECRET"),
  client: Nadia.Client.from_config(:support)
)

The Telegram secret token check uses the x-telegram-bot-api-secret-token header. If no :secret_token is supplied, verification is skipped.

Summary

Types

headers()

option()

Functions

context(body, opts \\ [])

Builds a Nadia.Context from a webhook body after optional secret validation.

dispatch_body(body, handler_or_routes, opts \\ [])

Dispatches a raw webhook body to a Nadia handler or route list.

parse_body(body)

Parses a raw Telegram webhook request body into an update.

parse_body!(body)

Parses a raw Telegram webhook request body into an update, raising on invalid JSON or invalid update shapes.

secret_token_header()

Returns the Telegram webhook secret token header name.

verify_secret(headers, expected_secret)

Verifies Telegram's optional webhook secret token header.

Types

headers()

@type headers() ::
  [{binary() | atom(), binary() | [binary()]}]
  | %{optional(binary() | atom()) => binary() | [binary()]}

option()

@type option() ::
  {:headers, headers()}
  | {:secret_token, binary() | nil}
  | {:client, Nadia.Client.t() | nil}
  | {:bot_username, binary()}

Functions

context(body, opts \\ [])

@spec context(binary() | map() | Nadia.Model.Update.t(), [option()] | map()) ::
  {:ok, Nadia.Context.t()} | {:error, term()}

Builds a Nadia.Context from a webhook body after optional secret validation.

dispatch_body(body, handler_or_routes, opts \\ [])

@spec dispatch_body(
  binary() | map() | Nadia.Model.Update.t(),
  module() | [Nadia.Dispatcher.route()],
  [option()] | map()
) :: term() | {:error, term()}

Dispatches a raw webhook body to a Nadia handler or route list.

Returns parser or secret verification errors as {:error, reason}. Handler results are returned unchanged, and handler exceptions bubble to the caller.

parse_body(body)

@spec parse_body(binary() | map() | Nadia.Model.Update.t()) ::
  {:ok, Nadia.Model.Update.t()} | {:error, term()}

Parses a raw Telegram webhook request body into an update.

parse_body!(body)

@spec parse_body!(binary() | map() | Nadia.Model.Update.t()) :: Nadia.Model.Update.t()

Parses a raw Telegram webhook request body into an update, raising on invalid JSON or invalid update shapes.

secret_token_header()

@spec secret_token_header() :: binary()

Returns the Telegram webhook secret token header name.

verify_secret(headers, expected_secret)

@spec verify_secret(headers(), binary() | nil) ::
  :ok | {:error, :invalid_secret_token}

Verifies Telegram's optional webhook secret token header.

Passing nil as the expected secret disables verification. Header names are matched case-insensitively.