API Webhooks

GET /api/v1/webhooks/endpoints

{
  "items": [
    {
      "id": "wh-3f8a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "url": "https://example.com/webhooks/puguh",
      "description": "Production webhook receiver",
      "events": ["user.created", "user.updated", "auth.login"],
      "is_active": true,
      "created_at": "2026-02-15T08:00:00Z",
      "updated_at": "2026-02-18T12:30:00Z"
    }
  ],
  "total": 3,
  "page": 1,
  "page_size": 20,
  "has_next": false,
  "has_prev": false
}

POST /api/v1/webhooks/endpoints
Content-Type: application/json

{
  "url": "https://example.com/webhooks/puguh",
  "events": ["user.created", "user.updated", "organization.updated"],
  "description": "Production webhook receiver",
  "secret": "whsec_your_custom_secret_key"
}

{
  "id": "wh-3f8a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "url": "https://example.com/webhooks/puguh",
  "description": "Production webhook receiver",
  "events": ["user.created", "user.updated", "organization.updated"],
  "signing_secret": "whsec_your_custom_secret_key",
  "is_active": true,
  "created_at": "2026-02-20T10:30:00Z",
  "updated_at": "2026-02-20T10:30:00Z"
}

GET /api/v1/webhooks/endpoints/{id}

{
  "id": "wh-3f8a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "url": "https://example.com/webhooks/puguh",
  "description": "Production webhook receiver",
  "events": ["user.created", "user.updated", "organization.updated"],
  "is_active": true,
  "created_at": "2026-02-15T08:00:00Z",
  "updated_at": "2026-02-18T12:30:00Z",
  "last_delivery_at": "2026-02-20T09:15:00Z",
  "delivery_stats": {
    "total": 142,
    "successful": 139,
    "failed": 3
  }
}

PATCH /api/v1/webhooks/endpoints/{id}
Content-Type: application/json

{
  "events": ["user.created", "user.updated", "user.deleted", "auth.login"],
  "is_active": true
}

{
  "id": "wh-3f8a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "url": "https://example.com/webhooks/puguh",
  "description": "Production webhook receiver",
  "events": ["user.created", "user.updated", "user.deleted", "auth.login"],
  "is_active": true,
  "created_at": "2026-02-15T08:00:00Z",
  "updated_at": "2026-02-20T11:00:00Z"
}

DELETE /api/v1/webhooks/endpoints/{id}

GET /api/v1/webhooks/events

[
  {
    "type": "user.created",
    "category": "user",
    "description": "A new user has been created"
  },
  {
    "type": "user.updated",
    "category": "user",
    "description": "A user profile has been updated"
  },
  {
    "type": "organization.created",
    "category": "organization",
    "description": "A new organization has been created"
  }
]

GET /api/v1/webhooks/endpoints/{id}/deliveries

{
  "items": [
    {
      "id": "del-a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
      "webhook_id": "wh-3f8a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "event": "user.created",
      "status": "success",
      "http_status": 200,
      "attempt": 1,
      "max_attempts": 5,
      "request_body": {
        "event": "user.created",
        "timestamp": "2026-02-20T10:30:00Z",
        "data": {
          "id": "usr-uuid",
          "email": "newuser@example.com"
        },
        "webhook_id": "wh-3f8a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
        "delivery_id": "del-a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d"
      },
      "response_body": "OK",
      "duration_ms": 120,
      "delivered_at": "2026-02-20T10:30:01Z",
      "next_retry_at": null
    },
    {
      "id": "del-b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
      "webhook_id": "wh-3f8a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "event": "auth.login",
      "status": "failed",
      "http_status": 500,
      "attempt": 3,
      "max_attempts": 5,
      "response_body": "Internal Server Error",
      "duration_ms": 5032,
      "delivered_at": "2026-02-20T09:15:05Z",
      "next_retry_at": "2026-02-20T10:15:05Z"
    }
  ],
  "total": 142,
  "page": 1,
  "page_size": 20,
  "has_next": true,
  "has_prev": false
}

POST /api/v1/webhooks/deliveries/{id}/retry

{
  "id": "del-b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
  "status": "pending",
  "attempt": 4,
  "max_attempts": 5,
  "next_retry_at": null,
  "queued_at": "2026-02-20T11:00:00Z"
}

{
  "event": "user.created",
  "timestamp": "2026-02-20T10:30:00Z",
  "data": {
    "id": "usr-a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
    "email": "newuser@example.com",
    "full_name": "Jane Doe",
    "created_at": "2026-02-20T10:30:00Z"
  },
  "webhook_id": "wh-3f8a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "delivery_id": "del-a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d"
}

import hmac
import hashlib
import time

def verify_webhook_signature(
    payload: bytes,
    signature_header: str,
    timestamp_header: str,
    secret: str,
    tolerance_seconds: int = 300
) -> bool:
    """Verify PUGUH webhook signature.

    Args:
        payload: Raw request body bytes.
        signature_header: Value of X-Puguh-Signature header.
        timestamp_header: Value of X-Puguh-Timestamp header.
        secret: Your webhook endpoint signing secret.
        tolerance_seconds: Max age in seconds (default 5 min).

    Returns:
        True if signature is valid and timestamp is within tolerance.
    """
    # 1. Check timestamp to prevent replay attacks
    try:
        timestamp = int(timestamp_header)
    except (ValueError, TypeError):
        return False

    if abs(time.time() - timestamp) > tolerance_seconds:
        return False

    # 2. Compute expected signature
    signed_content = f"{timestamp}.".encode() + payload
    expected = hmac.new(
        secret.encode(),
        signed_content,
        hashlib.sha256
    ).hexdigest()

    # 3. Compare using constant-time comparison
    expected_sig = f"sha256={expected}"
    return hmac.compare_digest(expected_sig, signature_header)


# Usage in a Flask/FastAPI handler
from fastapi import Request, HTTPException

WEBHOOK_SECRET = "whsec_your_signing_secret"

@app.post("/webhooks/puguh")
async def handle_webhook(request: Request):
    payload = await request.body()
    signature = request.headers.get("X-Puguh-Signature", "")
    timestamp = request.headers.get("X-Puguh-Timestamp", "")

    if not verify_webhook_signature(payload, signature, timestamp, WEBHOOK_SECRET):
        raise HTTPException(status_code=401, detail="Invalid signature")

    event = request.headers.get("X-Puguh-Event")
    data = await request.json()

    if event == "user.created":
        handle_user_created(data["data"])
    elif event == "billing.invoice.paid":
        handle_invoice_paid(data["data"])

    return {"received": True}

import { createHmac, timingSafeEqual } from "crypto";

function verifyWebhookSignature(
  payload: string,
  signatureHeader: string,
  timestampHeader: string,
  secret: string,
  toleranceSeconds: number = 300
): boolean {
  // 1. Check timestamp to prevent replay attacks
  const timestamp = parseInt(timestampHeader, 10);
  if (isNaN(timestamp)) return false;

  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > toleranceSeconds) return false;

  // 2. Compute expected signature
  const signedContent = `${timestamp}.${payload}`;
  const expectedHex = createHmac("sha256", secret)
    .update(signedContent)
    .digest("hex");

  const expectedSig = `sha256=${expectedHex}`;

  // 3. Compare using constant-time comparison
  if (expectedSig.length !== signatureHeader.length) return false;

  return timingSafeEqual(
    Buffer.from(expectedSig),
    Buffer.from(signatureHeader)
  );
}


// Usage in an Express handler
import express from "express";

const WEBHOOK_SECRET = process.env.PUGUH_WEBHOOK_SECRET!;

app.post(
  "/webhooks/puguh",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const payload = req.body.toString();
    const signature = req.headers["x-puguh-signature"] as string;
    const timestamp = req.headers["x-puguh-timestamp"] as string;

    if (!verifyWebhookSignature(payload, signature, timestamp, WEBHOOK_SECRET)) {
      return res.status(401).json({ detail: "Invalid signature" });
    }

    const event = req.headers["x-puguh-event"] as string;
    const data = JSON.parse(payload);

    switch (event) {
      case "user.created":
        handleUserCreated(data.data);
        break;
      case "billing.invoice.paid":
        handleInvoicePaid(data.data);
        break;
    }

    res.json({ received: true });
  }
);

{
  "detail": "Invalid URL: must be HTTPS"
}

{
  "detail": "Webhook endpoint not found"
}

{
  "detail": "Delivery is already in pending state"
}

{
  "detail": "Invalid event type: user.unknown. Use GET /webhooks/events for available types."
}