papers/hanzo-webhooks/sections/03-webhook-subscription-model.tex

\section{Webhook Subscription Model}


\subsection{Subscription Definition}

\begin{definition}[Webhook Subscription]
A subscription $s$ is a tuple $(id, merchant, url, events, secret, active)$ where:
\begin{itemize}
    \item $id$: subscription identifier
    \item $merchant$: owning merchant
    \item $url$: delivery endpoint URL (HTTPS required)
    \item $events \subseteq \mathcal{T}$: subscribed event types
    \item $secret$: shared secret for signature verification
    \item $active$: boolean enabled status
\end{itemize}
\end{definition}

\subsection{Event Matching}

Event $e$ matches subscription $s$ if:

\begin{equation}
matches(e, s) \iff e.merchant = s.merchant \land e.type \in s.events \land s.active
\end{equation}

Wildcard matching supported: \texttt{order.*} matches all order events.

\subsection{Subscription API}

\begin{lstlisting}[caption=Subscription Management]
# Create subscription
POST /v1/webhooks
{
  "url": "https://example.com/webhooks",
  "events": ["order.created", "order.fulfilled"],
  "secret": "whsec_..."
}

# List subscriptions
GET /v1/webhooks

# Update subscription
PUT /v1/webhooks/{id}

# Delete subscription
DELETE /v1/webhooks/{id}

# Test subscription
POST /v1/webhooks/{id}/test
\end{lstlisting}