papers/hanzo-webhooks/sections/06-security.tex

\section{Security}


\subsection{Signature Scheme}

Webhooks are signed using HMAC-SHA256:

\begin{definition}[Webhook Signature]
For payload $p$, timestamp $t$, and secret $k$:
\begin{equation}
signature = HMAC_{SHA256}(k, t || '.' || p)
\end{equation}
\end{definition}

Signature header format:

\begin{lstlisting}
X-Webhook-Signature: t=1548892800,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
\end{lstlisting}

\subsection{Verification Algorithm}

\begin{algorithm}
\caption{Signature Verification}
\begin{algorithmic}[1]
\Function{VerifySignature}{$payload$, $header$, $secret$}
    \State $components \gets parse(header)$
    \State $timestamp \gets components['t']$
    \State $signatures \gets components['v1']$
    \If{$|now - timestamp| > tolerance$}
        \State \Return \textsc{TimestampOutOfRange}
    \EndIf
    \State $expected \gets HMAC_{SHA256}(secret, timestamp || '.' || payload)$
    \If{$expected \in signatures$}
        \State \Return \textsc{Valid}
    \Else
        \State \Return \textsc{InvalidSignature}
    \EndIf
\EndFunction
\end{algorithmic}
\end{algorithm}

\subsection{Security Properties}

\begin{theorem}[Signature Unforgeability]
Without knowledge of secret $k$, an adversary cannot forge a valid signature with probability greater than $2^{-256}$.
\end{theorem}

\begin{theorem}[Replay Prevention]
Timestamp tolerance of 5 minutes limits replay window. Endpoints should additionally track processed event IDs.
\end{theorem}

\subsection{Endpoint Verification}

Before activating a subscription, we verify endpoint ownership:

\begin{lstlisting}[caption=Endpoint Verification Flow]
1. Generate verification token
2. POST to endpoint with verification challenge
3. Endpoint must return challenge in response
4. Subscription activated upon successful verification
\end{lstlisting}