GhEx.Webhooks (gh_ex v0.3.1)

Helpers for receiving GitHub webhooks: verify the delivery signature and decode the payload.

GitHub signs each delivery with an HMAC-SHA256 of the raw request body, keyed by the webhook secret, in the X-Hub-Signature-256 header (sha256=<hex>). The event name is in X-GitHub-Event. Read the raw body and those headers from your web framework, then verify and parse:

with :ok <- GhEx.Webhooks.verify(body, signature, secret),
     {:ok, payload} <- GhEx.Webhooks.parse(body) do
  handle(event_name, payload)
end

Payloads are returned as raw maps; dispatch on the event name and read the fields you need.

Summary

Functions

parse(payload)

Decodes a webhook payload (the raw JSON body) into a map.

verify(payload, arg2, secret)

Verifies a delivery signature in constant time.

Functions

parse(payload)

@spec parse(binary()) :: {:ok, map()} | {:error, term()}

Decodes a webhook payload (the raw JSON body) into a map.

Examples

iex> GhEx.Webhooks.parse(~s({"action": "opened", "number": 1}))
{:ok, %{"action" => "opened", "number" => 1}}

verify(payload, arg2, secret)

@spec verify(binary(), String.t() | nil, binary()) ::
  :ok | {:error, :invalid_signature | :missing_signature}

Verifies a delivery signature in constant time.

payload is the raw request body, signature is the X-Hub-Signature-256 header value ("sha256=<hex>"), and secret is the webhook secret. Returns :ok, {:error, :invalid_signature}, or {:error, :missing_signature} when the header is absent or not a sha256= value.