msaas-webhooks 0.1.0__py3-none-any.whl

msaas_webhooks-0.1.0.dist-info/METADATA

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: msaas-webhooks
+Version: 0.1.0
+Summary: Webhook delivery system with HMAC signing, retries, and FastAPI router
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: asyncpg>=0.30.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: msaas-api-core
+Requires-Dist: msaas-errors
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.22.0; extra == 'dev'
+Requires-Dist: time-machine>=2.13.0; extra == 'dev'

msaas_webhooks-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+webhooks/__init__.py,sha256=DanYCmP0-W27fyE0b9S4auo2hfKKIwBHf2A7TmHe_sc,766
+webhooks/config.py,sha256=OYAsRyCtJJ85jshHh8UuJeiPqlOOa2atELZxMFoTGoU,1436
+webhooks/delivery.py,sha256=QISa6DnfoYDwU2j_wG_KnNPo08-NofKAtIynge_vqIY,6613
+webhooks/models.py,sha256=ZAwuTGUrcjhCX4xxIzEdkN_JmVdEQo9mmPCdaA9Yf74,2367
+webhooks/router.py,sha256=V3xh6Z8zRQSIa3PuFliurb3eK2GholjVPK8buE6GtgQ,6181
+webhooks/signing.py,sha256=edW0sdKJnYCy-913bFyalW2naQSCBqr8KVCb4ex_zUU,1895
+webhooks/store.py,sha256=lCWKiTwwz9lOnQ4DCe97M3AmXzjdFCMta1C6AzWhFm0,2721
+webhooks/store_deliveries.py,sha256=nr3UoYOdFH_NrC6D8F1ykNmIMK3B_ZbE5tBK9ugKedQ,5538
+webhooks/store_endpoints.py,sha256=o77wsKG1uo3EjJl9aBpSiZ2Oop8D6TGOV_GigjZgU_w,4357
+msaas_webhooks-0.1.0.dist-info/METADATA,sha256=9foTo-6BfhSHDucj3ftxhEzgxobluC8qd2N7Fr0ilLY,568
+msaas_webhooks-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+msaas_webhooks-0.1.0.dist-info/RECORD,,

msaas_webhooks-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

webhooks/__init__.py

@@ -0,0 +1,28 @@
+"""Willian Webhooks -- Webhook delivery system with HMAC signing and retries."""
+
+from webhooks.config import WebhookConfig, init_webhooks
+from webhooks.delivery import deliver_webhook, dispatch_event, retry_failed_deliveries
+from webhooks.models import (
+    DeliveryStatus,
+    WebhookDelivery,
+    WebhookEndpoint,
+    WebhookEvent,
+)
+from webhooks.router import WebhookRouter
+from webhooks.signing import generate_secret, sign_payload, verify_signature
+
+__all__ = [
+    "DeliveryStatus",
+    "WebhookConfig",
+    "WebhookDelivery",
+    "WebhookEndpoint",
+    "WebhookEvent",
+    "WebhookRouter",
+    "deliver_webhook",
+    "dispatch_event",
+    "generate_secret",
+    "init_webhooks",
+    "retry_failed_deliveries",
+    "sign_payload",
+    "verify_signature",
+]

webhooks/config.py

@@ -0,0 +1,52 @@
+"""Webhook module configuration and initialization."""
+
+from __future__ import annotations
+
+import asyncpg
+from pydantic import BaseModel
+
+_config: WebhookConfig | None = None
+_pool: asyncpg.Pool | None = None
+
+
+class WebhookConfig(BaseModel):
+    """Configuration for the webhook module."""
+
+    database_url: str
+    max_retries: int = 5
+    retry_delay_seconds: int = 30
+    timeout_seconds: int = 10
+    signing_secret_prefix: str = "whsec_"
+
+
+async def init_webhooks(config: WebhookConfig) -> None:
+    """Initialize the webhook module with the given configuration.
+
+    Creates an asyncpg connection pool and stores the config globally.
+    Must be called before any store or delivery operations.
+    """
+    global _config, _pool
+    _config = config
+    _pool = await asyncpg.create_pool(dsn=config.database_url, min_size=2, max_size=10)
+
+
+def get_config() -> WebhookConfig:
+    """Return the current module configuration.
+
+    Raises:
+        RuntimeError: If init_webhooks() has not been called.
+    """
+    if _config is None:
+        raise RuntimeError("Webhook module not initialized. Call init_webhooks() first.")
+    return _config
+
+
+def get_pool() -> asyncpg.Pool:
+    """Return the current connection pool.
+
+    Raises:
+        RuntimeError: If init_webhooks() has not been called.
+    """
+    if _pool is None:
+        raise RuntimeError("Webhook module not initialized. Call init_webhooks() first.")
+    return _pool

webhooks/delivery.py

@@ -0,0 +1,213 @@
+"""Webhook delivery engine with retry support."""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from datetime import UTC, datetime
+
+import httpx
+
+from webhooks.config import get_config
+from webhooks.models import (
+    DeliveryStatus,
+    WebhookDelivery,
+    WebhookEndpoint,
+    WebhookEvent,
+)
+from webhooks.signing import sign_payload
+from webhooks.store import (
+    get_delivery,
+    get_endpoint,
+    get_failed_deliveries,
+    list_endpoints,
+    record_delivery,
+    update_delivery,
+)
+
+logger = logging.getLogger(__name__)
+
+
+async def deliver_webhook(
+    endpoint: WebhookEndpoint,
+    event: WebhookEvent,
+) -> WebhookDelivery:
+    """Send a single webhook HTTP POST to the endpoint.
+
+    Creates a delivery record, sends the request with signed headers,
+    and updates the delivery with the result.
+
+    Args:
+        endpoint: The target webhook endpoint.
+        event: The event to deliver.
+
+    Returns:
+        The updated WebhookDelivery record.
+    """
+    config = get_config()
+    payload_str = json.dumps(event.payload, default=str, sort_keys=True)
+    timestamp = int(time.time())
+    signature = sign_payload(payload_str, endpoint.secret, timestamp)
+
+    delivery = await record_delivery(
+        endpoint_id=endpoint.id,
+        event_type=event.event_type,
+        payload=event.payload,
+    )
+
+    headers = {
+        "Content-Type": "application/json",
+        "X-Webhook-ID": str(delivery.id),
+        "X-Webhook-Timestamp": str(timestamp),
+        "X-Webhook-Signature": signature,
+    }
+
+    try:
+        async with httpx.AsyncClient(timeout=config.timeout_seconds) as client:
+            response = await client.post(
+                endpoint.url,
+                content=payload_str,
+                headers=headers,
+            )
+
+        is_success = 200 <= response.status_code < 300
+        status = DeliveryStatus.SUCCESS if is_success else DeliveryStatus.FAILED
+        response_body = response.text[:2000] if response.text else None
+
+        await update_delivery(
+            delivery.id,
+            status=status,
+            attempts=1,
+            response_status=response.status_code,
+            response_body=response_body,
+        )
+
+        if is_success:
+            logger.info(
+                "Webhook delivered successfully",
+                extra={"delivery_id": str(delivery.id), "endpoint_url": endpoint.url},
+            )
+        else:
+            logger.warning(
+                "Webhook delivery failed with status %d",
+                response.status_code,
+                extra={"delivery_id": str(delivery.id), "endpoint_url": endpoint.url},
+            )
+
+    except httpx.HTTPError as exc:
+        logger.error(
+            "Webhook delivery error: %s",
+            str(exc),
+            extra={"delivery_id": str(delivery.id), "endpoint_url": endpoint.url},
+        )
+        await update_delivery(
+            delivery.id,
+            status=DeliveryStatus.FAILED,
+            attempts=1,
+            response_body=str(exc)[:2000],
+        )
+
+    # Re-fetch to return the updated state
+    updated = await get_delivery(delivery.id)
+    return updated or delivery
+
+
+async def retry_failed_deliveries() -> list[WebhookDelivery]:
+    """Retry all failed deliveries that haven't exceeded max attempts.
+
+    Uses exponential backoff: only retries deliveries whose last attempt
+    was at least ``retry_delay_seconds * 2^(attempts-1)`` seconds ago.
+
+    Returns:
+        List of delivery records that were retried.
+    """
+    config = get_config()
+    failed = await get_failed_deliveries(max_attempts=config.max_retries)
+    retried: list[WebhookDelivery] = []
+
+    now = datetime.now(UTC)
+
+    for delivery in failed:
+        # Exponential backoff check
+        if delivery.last_attempt_at is not None:
+            backoff = config.retry_delay_seconds * (2 ** (delivery.attempts - 1))
+            elapsed = (now - delivery.last_attempt_at).total_seconds()
+            if elapsed < backoff:
+                continue
+
+        # Fetch the endpoint to get its URL and secret
+        endpoint = await get_endpoint(delivery.endpoint_id)
+        if endpoint is None or not endpoint.active:
+            continue
+
+        payload_str = json.dumps(delivery.payload, default=str, sort_keys=True)
+        timestamp = int(time.time())
+        signature = sign_payload(payload_str, endpoint.secret, timestamp)
+
+        headers = {
+            "Content-Type": "application/json",
+            "X-Webhook-ID": str(delivery.id),
+            "X-Webhook-Timestamp": str(timestamp),
+            "X-Webhook-Signature": signature,
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=config.timeout_seconds) as client:
+                response = await client.post(
+                    endpoint.url,
+                    content=payload_str,
+                    headers=headers,
+                )
+
+            is_success = 200 <= response.status_code < 300
+            status = DeliveryStatus.SUCCESS if is_success else DeliveryStatus.FAILED
+
+            await update_delivery(
+                delivery.id,
+                status=status,
+                attempts=delivery.attempts + 1,
+                response_status=response.status_code,
+                response_body=(response.text[:2000] if response.text else None),
+            )
+
+        except httpx.HTTPError as exc:
+            await update_delivery(
+                delivery.id,
+                status=DeliveryStatus.FAILED,
+                attempts=delivery.attempts + 1,
+                response_body=str(exc)[:2000],
+            )
+
+        updated = await get_delivery(delivery.id)
+        if updated:
+            retried.append(updated)
+
+    return retried
+
+
+async def dispatch_event(event_type: str, payload: dict) -> list[WebhookDelivery]:
+    """Dispatch an event to all active endpoints subscribed to it.
+
+    Args:
+        event_type: The event type string (e.g. ``"order.created"``).
+        payload: The event payload dictionary.
+
+    Returns:
+        List of delivery records for each endpoint that was notified.
+    """
+    endpoints = await list_endpoints(active_only=True)
+    event = WebhookEvent(
+        event_type=event_type,
+        payload=payload,
+        timestamp=datetime.now(UTC),
+    )
+
+    deliveries: list[WebhookDelivery] = []
+    for endpoint in endpoints:
+        # Check if this endpoint subscribes to the event type or uses wildcard
+        if "*" in endpoint.events or event_type in endpoint.events:
+            delivery = await deliver_webhook(endpoint, event)
+            deliveries.append(delivery)
+
+    return deliveries

webhooks/models.py

@@ -0,0 +1,99 @@
+"""Pydantic models for the webhook module."""
+
+from __future__ import annotations
+
+import enum
+from datetime import datetime
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+class DeliveryStatus(str, enum.Enum):
+    """Status of a webhook delivery attempt."""
+
+    PENDING = "pending"
+    SUCCESS = "success"
+    FAILED = "failed"
+
+
+class WebhookEndpoint(BaseModel):
+    """A registered webhook endpoint."""
+
+    id: UUID
+    url: str
+    events: list[str] = Field(description="Subscribed event types")
+    secret: str = Field(description="HMAC signing key")
+    active: bool = True
+    created_at: datetime
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class WebhookDelivery(BaseModel):
+    """Record of a webhook delivery attempt."""
+
+    id: UUID
+    endpoint_id: UUID
+    event_type: str
+    payload: dict[str, Any]
+    status: DeliveryStatus = DeliveryStatus.PENDING
+    attempts: int = 0
+    last_attempt_at: datetime | None = None
+    response_status: int | None = None
+    response_body: str | None = None
+    created_at: datetime
+
+
+class WebhookEvent(BaseModel):
+    """An event to be dispatched to webhook endpoints."""
+
+    event_type: str
+    payload: dict[str, Any]
+    timestamp: datetime
+
+
+# --- Request/Response models for the API layer ---
+
+
+class CreateEndpointRequest(BaseModel):
+    """Payload for registering a new webhook endpoint."""
+
+    url: str = Field(min_length=1)
+    events: list[str] = Field(min_length=1)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class UpdateEndpointRequest(BaseModel):
+    """Payload for updating an existing webhook endpoint."""
+
+    url: str | None = None
+    events: list[str] | None = None
+    active: bool | None = None
+    metadata: dict[str, Any] | None = None
+
+
+class EndpointResponse(BaseModel):
+    """Response model for a webhook endpoint (hides full secret)."""
+
+    id: UUID
+    url: str
+    events: list[str]
+    secret: str = Field(description="Signing secret (shown once on creation)")
+    active: bool
+    created_at: datetime
+    metadata: dict[str, Any]
+
+
+class DeliveryListResponse(BaseModel):
+    """Paginated list of deliveries."""
+
+    items: list[WebhookDelivery]
+    total: int
+
+
+class TestEventResponse(BaseModel):
+    """Response after sending a test webhook event."""
+
+    delivery_id: UUID
+    status: DeliveryStatus

webhooks/router.py

@@ -0,0 +1,177 @@
+"""FastAPI router for webhook management endpoints."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from uuid import UUID
+
+from errors import (
+    NotFoundError,
+    ValidationError,
+)
+from fastapi import APIRouter, Query
+
+from webhooks.delivery import deliver_webhook
+from webhooks.models import (
+    CreateEndpointRequest,
+    DeliveryListResponse,
+    DeliveryStatus,
+    EndpointResponse,
+    TestEventResponse,
+    UpdateEndpointRequest,
+    WebhookDelivery,
+    WebhookEndpoint,
+    WebhookEvent,
+)
+from webhooks.signing import generate_secret
+from webhooks.store import (
+    create_endpoint,
+    delete_endpoint,
+    get_deliveries,
+    get_deliveries_count,
+    get_delivery,
+    get_endpoint,
+    list_endpoints,
+    update_endpoint,
+)
+
+
+def _endpoint_to_response(ep: WebhookEndpoint) -> EndpointResponse:
+    """Convert internal endpoint model to API response."""
+    return EndpointResponse(
+        id=ep.id,
+        url=ep.url,
+        events=ep.events,
+        secret=ep.secret,
+        active=ep.active,
+        created_at=ep.created_at,
+        metadata=ep.metadata,
+    )
+
+
+def WebhookRouter(
+    *,
+    prefix: str = "/webhooks",
+    tags: list[str] | None = None,
+) -> APIRouter:
+    """Create a FastAPI router for webhook management endpoints.
+
+    Args:
+        prefix: URL prefix for all routes. Defaults to ``/webhooks``.
+        tags: OpenAPI tags for the router.
+
+    Returns:
+        A configured APIRouter.
+
+    Example::
+
+        router = WebhookRouter()
+        app.include_router(router)
+    """
+    router = APIRouter(prefix=prefix, tags=tags or ["webhooks"])
+
+    @router.post("/endpoints", response_model=EndpointResponse, status_code=201)
+    async def register_endpoint(body: CreateEndpointRequest) -> EndpointResponse:
+        """Register a new webhook endpoint."""
+        secret = generate_secret()
+        endpoint = await create_endpoint(
+            url=body.url,
+            events=body.events,
+            secret=secret,
+            metadata=body.metadata,
+        )
+        return _endpoint_to_response(endpoint)
+
+    @router.get("/endpoints", response_model=list[EndpointResponse])
+    async def list_all_endpoints(
+        active_only: bool = Query(False, description="Only return active endpoints"),
+    ) -> list[EndpointResponse]:
+        """List all registered webhook endpoints."""
+        endpoints = await list_endpoints(active_only=active_only)
+        return [_endpoint_to_response(ep) for ep in endpoints]
+
+    @router.get("/endpoints/{endpoint_id}", response_model=EndpointResponse)
+    async def get_single_endpoint(endpoint_id: UUID) -> EndpointResponse:
+        """Get a single webhook endpoint by ID."""
+        endpoint = await get_endpoint(endpoint_id)
+        if endpoint is None:
+            raise NotFoundError("Endpoint not found")
+        return _endpoint_to_response(endpoint)
+
+    @router.patch("/endpoints/{endpoint_id}", response_model=EndpointResponse)
+    async def patch_endpoint(endpoint_id: UUID, body: UpdateEndpointRequest) -> EndpointResponse:
+        """Update an existing webhook endpoint."""
+        updated = await update_endpoint(
+            endpoint_id,
+            url=body.url,
+            events=body.events,
+            active=body.active,
+            metadata=body.metadata,
+        )
+        if updated is None:
+            raise NotFoundError("Endpoint not found")
+        return _endpoint_to_response(updated)
+
+    @router.delete("/endpoints/{endpoint_id}", status_code=204)
+    async def remove_endpoint(endpoint_id: UUID) -> None:
+        """Delete a webhook endpoint."""
+        deleted = await delete_endpoint(endpoint_id)
+        if not deleted:
+            raise NotFoundError("Endpoint not found")
+
+    @router.get("/deliveries", response_model=DeliveryListResponse)
+    async def list_deliveries(
+        endpoint_id: UUID | None = Query(None, description="Filter by endpoint"),
+        status: DeliveryStatus | None = Query(None, description="Filter by status"),
+        limit: int = Query(50, ge=1, le=200),
+        offset: int = Query(0, ge=0),
+    ) -> DeliveryListResponse:
+        """List webhook deliveries with optional filters."""
+        items = await get_deliveries(
+            endpoint_id=endpoint_id,
+            status=status,
+            limit=limit,
+            offset=offset,
+        )
+        total = await get_deliveries_count(endpoint_id=endpoint_id, status=status)
+        return DeliveryListResponse(items=items, total=total)
+
+    @router.post("/deliveries/{delivery_id}/retry", response_model=WebhookDelivery)
+    async def retry_delivery(delivery_id: UUID) -> WebhookDelivery:
+        """Retry a single failed delivery."""
+        delivery = await get_delivery(delivery_id)
+        if delivery is None:
+            raise NotFoundError("Delivery not found")
+        if delivery.status != DeliveryStatus.FAILED:
+            raise ValidationError("Only failed deliveries can be retried")
+
+        endpoint = await get_endpoint(delivery.endpoint_id)
+        if endpoint is None or not endpoint.active:
+            raise ValidationError("Endpoint not found or inactive")
+
+        event = WebhookEvent(
+            event_type=delivery.event_type,
+            payload=delivery.payload,
+            timestamp=datetime.now(UTC),
+        )
+        result = await deliver_webhook(endpoint, event)
+        return result
+
+    @router.post("/test/{endpoint_id}", response_model=TestEventResponse)
+    async def send_test_event(endpoint_id: UUID) -> TestEventResponse:
+        """Send a test webhook event to the specified endpoint."""
+        endpoint = await get_endpoint(endpoint_id)
+        if endpoint is None:
+            raise NotFoundError("Endpoint not found")
+        if not endpoint.active:
+            raise ValidationError("Endpoint is inactive")
+
+        event = WebhookEvent(
+            event_type="webhook.test",
+            payload={"message": "This is a test webhook event", "endpoint_id": str(endpoint_id)},
+            timestamp=datetime.now(UTC),
+        )
+        delivery = await deliver_webhook(endpoint, event)
+        return TestEventResponse(delivery_id=delivery.id, status=delivery.status)
+
+    return router

webhooks/signing.py

@@ -0,0 +1,70 @@
+"""HMAC-SHA256 webhook signing and verification."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import secrets
+import time
+
+from webhooks.config import get_config
+
+
+def generate_secret() -> str:
+    """Generate a new webhook signing secret with the configured prefix.
+
+    Returns:
+        A string like ``whsec_<32-hex-chars>``.
+    """
+    config = get_config()
+    token = secrets.token_hex(32)
+    return f"{config.signing_secret_prefix}{token}"
+
+
+def sign_payload(payload: str, secret: str, timestamp: int) -> str:
+    """Create an HMAC-SHA256 signature for the given payload.
+
+    The signed message is ``{timestamp}.{payload}`` to bind the signature to
+    a specific point in time.
+
+    Args:
+        payload: The JSON string body to sign.
+        secret: The endpoint's signing secret.
+        timestamp: Unix timestamp (seconds) when the event was sent.
+
+    Returns:
+        Hex-encoded HMAC-SHA256 signature.
+    """
+    message = f"{timestamp}.{payload}"
+    return hmac.new(
+        secret.encode("utf-8"),
+        message.encode("utf-8"),
+        hashlib.sha256,
+    ).hexdigest()
+
+
+def verify_signature(
+    payload: str,
+    signature: str,
+    secret: str,
+    timestamp: int,
+    tolerance: int = 300,
+) -> bool:
+    """Verify an HMAC-SHA256 webhook signature.
+
+    Args:
+        payload: The JSON string body that was signed.
+        signature: The hex-encoded signature to verify.
+        secret: The endpoint's signing secret.
+        timestamp: Unix timestamp claimed by the sender.
+        tolerance: Maximum allowed age in seconds (default 5 minutes).
+
+    Returns:
+        True if the signature is valid and the timestamp is within tolerance.
+    """
+    now = int(time.time())
+    if abs(now - timestamp) > tolerance:
+        return False
+
+    expected = sign_payload(payload, secret, timestamp)
+    return hmac.compare_digest(expected, signature)

webhooks/store.py

@@ -0,0 +1,83 @@
+"""PostgreSQL storage operations for webhooks -- facade module.
+
+Splits endpoint and delivery operations into separate files for readability,
+but re-exports everything here so callers can ``from webhooks.store import ...``.
+"""
+
+from __future__ import annotations
+
+from webhooks.config import get_pool
+from webhooks.store_deliveries import (
+    get_deliveries,
+    get_deliveries_count,
+    get_delivery,
+    get_failed_deliveries,
+    record_delivery,
+    update_delivery,
+)
+from webhooks.store_endpoints import (
+    create_endpoint,
+    delete_endpoint,
+    get_endpoint,
+    list_endpoints,
+    update_endpoint,
+)
+
+
+async def create_tables() -> None:
+    """Create the webhook_endpoints and webhook_deliveries tables if they do not exist."""
+    pool = get_pool()
+    async with pool.acquire() as conn:
+        await conn.execute("""
+            CREATE TABLE IF NOT EXISTS webhook_endpoints (
+                id UUID PRIMARY KEY,
+                url TEXT NOT NULL,
+                events JSONB NOT NULL DEFAULT '[]',
+                secret TEXT NOT NULL,
+                active BOOLEAN NOT NULL DEFAULT TRUE,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                metadata JSONB NOT NULL DEFAULT '{}'
+            )
+        """)
+        await conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_webhook_endpoints_active
+            ON webhook_endpoints (active) WHERE active = TRUE
+        """)
+        await conn.execute("""
+            CREATE TABLE IF NOT EXISTS webhook_deliveries (
+                id UUID PRIMARY KEY,
+                endpoint_id UUID NOT NULL REFERENCES webhook_endpoints(id) ON DELETE CASCADE,
+                event_type TEXT NOT NULL,
+                payload JSONB NOT NULL DEFAULT '{}',
+                status TEXT NOT NULL DEFAULT 'pending',
+                attempts INTEGER NOT NULL DEFAULT 0,
+                last_attempt_at TIMESTAMPTZ,
+                response_status INTEGER,
+                response_body TEXT,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+            )
+        """)
+        await conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_webhook_deliveries_endpoint
+            ON webhook_deliveries (endpoint_id, created_at DESC)
+        """)
+        await conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_webhook_deliveries_failed
+            ON webhook_deliveries (status) WHERE status = 'failed'
+        """)
+
+
+__all__ = [
+    "create_endpoint",
+    "create_tables",
+    "delete_endpoint",
+    "get_deliveries",
+    "get_deliveries_count",
+    "get_delivery",
+    "get_endpoint",
+    "get_failed_deliveries",
+    "list_endpoints",
+    "record_delivery",
+    "update_delivery",
+    "update_endpoint",
+]

webhooks/store_deliveries.py

@@ -0,0 +1,194 @@
+"""PostgreSQL storage operations for webhook deliveries (asyncpg, no ORM)."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+from webhooks.config import get_pool
+from webhooks.models import DeliveryStatus, WebhookDelivery
+
+_DELIVERY_COLS = (
+    "id, endpoint_id, event_type, payload, status, attempts,"
+    " last_attempt_at, response_status, response_body, created_at"
+)
+
+
+def _row_to_delivery(row: dict) -> WebhookDelivery:
+    """Convert an asyncpg Record to a WebhookDelivery model."""
+    payload = row["payload"]
+    if isinstance(payload, str):
+        payload = json.loads(payload)
+    return WebhookDelivery(
+        id=row["id"],
+        endpoint_id=row["endpoint_id"],
+        event_type=row["event_type"],
+        payload=payload,
+        status=DeliveryStatus(row["status"]),
+        attempts=row["attempts"],
+        last_attempt_at=row["last_attempt_at"],
+        response_status=row["response_status"],
+        response_body=row["response_body"],
+        created_at=row["created_at"],
+    )
+
+
+async def record_delivery(
+    endpoint_id: uuid.UUID,
+    event_type: str,
+    payload: dict[str, Any],
+) -> WebhookDelivery:
+    """Record a new pending delivery."""
+    pool = get_pool()
+    delivery_id = uuid.uuid4()
+    now = datetime.now(UTC)
+
+    async with pool.acquire() as conn:
+        await conn.execute(
+            """
+            INSERT INTO webhook_deliveries
+                (id, endpoint_id, event_type, payload, status, attempts, created_at)
+            VALUES ($1, $2, $3, $4::jsonb, 'pending', 0, $5)
+            """,
+            delivery_id,
+            endpoint_id,
+            event_type,
+            json.dumps(payload),
+            now,
+        )
+
+    return WebhookDelivery(
+        id=delivery_id,
+        endpoint_id=endpoint_id,
+        event_type=event_type,
+        payload=payload,
+        status=DeliveryStatus.PENDING,
+        attempts=0,
+        last_attempt_at=None,
+        response_status=None,
+        response_body=None,
+        created_at=now,
+    )
+
+
+async def update_delivery(
+    delivery_id: uuid.UUID,
+    *,
+    status: DeliveryStatus,
+    attempts: int,
+    response_status: int | None = None,
+    response_body: str | None = None,
+) -> None:
+    """Update a delivery record after an attempt."""
+    pool = get_pool()
+    now = datetime.now(UTC)
+    async with pool.acquire() as conn:
+        await conn.execute(
+            """
+            UPDATE webhook_deliveries
+            SET status = $1, attempts = $2, last_attempt_at = $3,
+                response_status = $4, response_body = $5
+            WHERE id = $6
+            """,
+            status.value,
+            attempts,
+            now,
+            response_status,
+            response_body,
+            delivery_id,
+        )
+
+
+async def get_delivery(delivery_id: uuid.UUID) -> WebhookDelivery | None:
+    """Fetch a single delivery by ID."""
+    pool = get_pool()
+    async with pool.acquire() as conn:
+        row = await conn.fetchrow(
+            f"SELECT {_DELIVERY_COLS} FROM webhook_deliveries WHERE id = $1",
+            delivery_id,
+        )
+    if row is None:
+        return None
+    return _row_to_delivery(dict(row))
+
+
+async def get_deliveries(
+    endpoint_id: uuid.UUID | None = None,
+    status: DeliveryStatus | None = None,
+    limit: int = 50,
+    offset: int = 0,
+) -> list[WebhookDelivery]:
+    """Fetch deliveries with optional filters."""
+    pool = get_pool()
+    conditions: list[str] = []
+    args: list[Any] = []
+    idx = 1
+
+    if endpoint_id is not None:
+        conditions.append(f"endpoint_id = ${idx}")
+        args.append(endpoint_id)
+        idx += 1
+    if status is not None:
+        conditions.append(f"status = ${idx}")
+        args.append(status.value)
+        idx += 1
+
+    where = f"WHERE {' AND '.join(conditions)}" if conditions else ""
+    query = f"""
+        SELECT {_DELIVERY_COLS}
+        FROM webhook_deliveries {where}
+        ORDER BY created_at DESC
+        LIMIT ${idx} OFFSET ${idx + 1}
+    """
+    args.extend([limit, offset])
+
+    async with pool.acquire() as conn:
+        rows = await conn.fetch(query, *args)
+
+    return [_row_to_delivery(dict(row)) for row in rows]
+
+
+async def get_deliveries_count(
+    endpoint_id: uuid.UUID | None = None,
+    status: DeliveryStatus | None = None,
+) -> int:
+    """Count deliveries with optional filters."""
+    pool = get_pool()
+    conditions: list[str] = []
+    args: list[Any] = []
+    idx = 1
+
+    if endpoint_id is not None:
+        conditions.append(f"endpoint_id = ${idx}")
+        args.append(endpoint_id)
+        idx += 1
+    if status is not None:
+        conditions.append(f"status = ${idx}")
+        args.append(status.value)
+        idx += 1
+
+    where = f"WHERE {' AND '.join(conditions)}" if conditions else ""
+    query = f"SELECT COUNT(*) FROM webhook_deliveries {where}"
+
+    async with pool.acquire() as conn:
+        count = await conn.fetchval(query, *args)
+
+    return count or 0
+
+
+async def get_failed_deliveries(max_attempts: int = 5) -> list[WebhookDelivery]:
+    """Fetch failed deliveries that haven't exceeded max retry attempts."""
+    pool = get_pool()
+    async with pool.acquire() as conn:
+        rows = await conn.fetch(
+            f"""
+            SELECT {_DELIVERY_COLS}
+            FROM webhook_deliveries
+            WHERE status = 'failed' AND attempts < $1
+            ORDER BY created_at ASC
+            """,
+            max_attempts,
+        )
+    return [_row_to_delivery(dict(row)) for row in rows]

webhooks/store_endpoints.py

@@ -0,0 +1,153 @@
+"""PostgreSQL storage operations for webhook endpoints (asyncpg, no ORM)."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+from webhooks.config import get_pool
+from webhooks.models import WebhookEndpoint
+
+_ENDPOINT_COLS = "id, url, events, secret, active, created_at, metadata"
+
+
+def _row_to_endpoint(row: dict) -> WebhookEndpoint:
+    """Convert an asyncpg Record to a WebhookEndpoint model."""
+    events = row["events"]
+    if isinstance(events, str):
+        events = json.loads(events)
+    metadata = row["metadata"]
+    if isinstance(metadata, str):
+        metadata = json.loads(metadata)
+    return WebhookEndpoint(
+        id=row["id"],
+        url=row["url"],
+        events=events,
+        secret=row["secret"],
+        active=row["active"],
+        created_at=row["created_at"],
+        metadata=metadata,
+    )
+
+
+async def create_endpoint(
+    url: str,
+    events: list[str],
+    secret: str,
+    metadata: dict[str, Any] | None = None,
+) -> WebhookEndpoint:
+    """Insert a new webhook endpoint and return it."""
+    pool = get_pool()
+    endpoint_id = uuid.uuid4()
+    now = datetime.now(UTC)
+    meta = metadata or {}
+
+    async with pool.acquire() as conn:
+        await conn.execute(
+            """
+            INSERT INTO webhook_endpoints (id, url, events, secret, active, created_at, metadata)
+            VALUES ($1, $2, $3::jsonb, $4, TRUE, $5, $6::jsonb)
+            """,
+            endpoint_id,
+            url,
+            json.dumps(events),
+            secret,
+            now,
+            json.dumps(meta),
+        )
+
+    return WebhookEndpoint(
+        id=endpoint_id,
+        url=url,
+        events=events,
+        secret=secret,
+        active=True,
+        created_at=now,
+        metadata=meta,
+    )
+
+
+async def get_endpoint(endpoint_id: uuid.UUID) -> WebhookEndpoint | None:
+    """Fetch a single endpoint by ID. Returns None if not found."""
+    pool = get_pool()
+    async with pool.acquire() as conn:
+        row = await conn.fetchrow(
+            f"SELECT {_ENDPOINT_COLS} FROM webhook_endpoints WHERE id = $1",
+            endpoint_id,
+        )
+    if row is None:
+        return None
+    return _row_to_endpoint(dict(row))
+
+
+async def list_endpoints(active_only: bool = False) -> list[WebhookEndpoint]:
+    """List all webhook endpoints, optionally filtering to active ones."""
+    pool = get_pool()
+    where = "WHERE active = TRUE" if active_only else ""
+    async with pool.acquire() as conn:
+        rows = await conn.fetch(
+            f"SELECT {_ENDPOINT_COLS} FROM webhook_endpoints {where} ORDER BY created_at DESC"
+        )
+    return [_row_to_endpoint(dict(row)) for row in rows]
+
+
+async def update_endpoint(
+    endpoint_id: uuid.UUID,
+    *,
+    url: str | None = None,
+    events: list[str] | None = None,
+    active: bool | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> WebhookEndpoint | None:
+    """Update an endpoint's fields. Returns the updated endpoint or None if not found."""
+    pool = get_pool()
+    sets: list[str] = []
+    args: list[Any] = []
+    idx = 1
+
+    if url is not None:
+        sets.append(f"url = ${idx}")
+        args.append(url)
+        idx += 1
+    if events is not None:
+        sets.append(f"events = ${idx}::jsonb")
+        args.append(json.dumps(events))
+        idx += 1
+    if active is not None:
+        sets.append(f"active = ${idx}")
+        args.append(active)
+        idx += 1
+    if metadata is not None:
+        sets.append(f"metadata = ${idx}::jsonb")
+        args.append(json.dumps(metadata))
+        idx += 1
+
+    if not sets:
+        return await get_endpoint(endpoint_id)
+
+    args.append(endpoint_id)
+    query = f"""
+        UPDATE webhook_endpoints SET {", ".join(sets)}
+        WHERE id = ${idx}
+        RETURNING {_ENDPOINT_COLS}
+    """
+
+    async with pool.acquire() as conn:
+        row = await conn.fetchrow(query, *args)
+
+    if row is None:
+        return None
+    return _row_to_endpoint(dict(row))
+
+
+async def delete_endpoint(endpoint_id: uuid.UUID) -> bool:
+    """Delete an endpoint by ID. Returns True if it existed."""
+    pool = get_pool()
+    async with pool.acquire() as conn:
+        result = await conn.execute(
+            "DELETE FROM webhook_endpoints WHERE id = $1",
+            endpoint_id,
+        )
+    return result == "DELETE 1"