Verifies and decodes webhooks sent by Kapso.

Kapso signs every webhook (project webhooks and both kapso and meta kind phone number webhooks) with an HMAC-SHA256 of the raw request body using the webhook's secret_key, hex encoded, in the X-Webhook-Signature header.

Other useful headers:

• X-Webhook-Event - event name, for example whatsapp.message.received.
• X-Idempotency-Key - unique per delivery; use it to drop duplicates, since webhooks can be delivered more than once.
• X-Webhook-Batch: true - the body is a batch envelope (%{"batch" => true, "data" => [...]}); see payloads/1.

Phoenix example

The signature must be computed over the exact bytes Kapso sent, so keep a copy of the raw body with KapsoEx.Webhook.CacheBodyReader:

# endpoint.ex
plug Plug.Parsers,
  parsers: [:urlencoded, :multipart, :json],
  pass: ["*/*"],
  body_reader: {KapsoEx.Webhook.CacheBodyReader, :read_body, []},
  json_decoder: Jason

# controller
def create(conn, _params) do
  raw_body = KapsoEx.Webhook.CacheBodyReader.raw_body(conn)
  [signature] = get_req_header(conn, "x-webhook-signature")
  [event] = get_req_header(conn, "x-webhook-event")

  case KapsoEx.Webhook.construct_event(raw_body, signature, webhook_secret()) do
    {:ok, body} ->
      for payload <- KapsoEx.Webhook.payloads(body), do: MyApp.handle(event, payload)
      send_resp(conn, 200, "ok")

    {:error, _reason} ->
      send_resp(conn, 401, "invalid signature")
  end
end

Respond within 10 seconds and move heavy work to a background job.