P
PUGUH
ID Get Started

Webhooks

Webhooks allow your application to receive real-time HTTP notifications when events occur in PUGUH.

How Webhooks Work

  1. You register an endpoint URL in PUGUH
  2. You subscribe to specific event types
  3. When an event occurs, PUGUH sends an HTTP POST to your endpoint
  4. Your server processes the payload and responds with 200 OK

Event Types

PUGUH emits events across all infrastructure modules:

Identity Events

EventDescription
user.createdNew user registered
user.updatedUser profile changed
user.deletedUser account deleted
auth.loginUser logged in
auth.logoutUser logged out
auth.password_changedPassword was changed
auth.mfa_enabledMFA activated

Organization Events

EventDescription
organization.createdNew organization created
organization.updatedOrganization settings changed
member.invitedMember invited
member.joinedMember accepted invitation
member.removedMember removed
member.role_changedMember role updated

Billing Events

EventDescription
billing.subscription.createdNew subscription started
billing.subscription.updatedPlan changed
billing.subscription.cancelledSubscription cancelled
billing.invoice.paidInvoice payment received
billing.invoice.overduePayment past due

Creating an Endpoint

Via API

bash 
curl -X POST https://api-puguh.arsaka.io/webhooks/endpoints \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Organization-ID: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/puguh",
    "events": ["user.created", "member.invited", "billing.invoice.paid"],
    "description": "Production webhook"
  }'

Response:

json 
{
  "id": "wh_abc123",
  "url": "https://your-app.com/webhooks/puguh",
  "events": ["user.created", "member.invited", "billing.invoice.paid"],
  "secret": "whsec_xxxxxxxxxxxxxxxx",
  "is_active": true,
  "created_at": "2026-02-20T10:00:00Z"
}

Important

The secret is only returned once at creation. Save it securely for signature verification.

Webhook Payload

Each delivery sends a JSON POST request:

json 
{
  "event": "member.invited",
  "timestamp": "2026-02-20T10:30:00Z",
  "data": {
    "organization_id": "org_abc",
    "email": "new-member@example.com",
    "role": "member",
    "invited_by": "admin@example.com"
  },
  "webhook_id": "wh_abc123",
  "delivery_id": "del_xyz789"
}

Headers

HeaderDescription
Content-Typeapplication/json
X-Puguh-SignatureHMAC-SHA256 signature
X-Puguh-Delivery-IDUnique delivery identifier
X-Puguh-EventEvent type (e.g. user.created)

Verifying Signatures

Always verify the X-Puguh-Signature header to ensure the request is from PUGUH.

Python

python 
import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

TypeScript

typescript 
import { createHmac, timingSafeEqual } from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = `sha256=${createHmac('sha256', secret).update(payload).digest('hex')}`;
  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Retry Policy

If your endpoint returns a non-2xx status, PUGUH retries with exponential backoff:

AttemptDelay
1st retry1 minute
2nd retry5 minutes
3rd retry30 minutes
4th retry2 hours
5th retry12 hours

After 5 failed attempts, the delivery is moved to the dead letter queue. You can manually retry from the dashboard or API.

Managing Endpoints

List Endpoints

bash 
curl https://api-puguh.arsaka.io/webhooks/endpoints \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Organization-ID: YOUR_ORG_ID"

Update Endpoint

bash 
curl -X PUT https://api-puguh.arsaka.io/webhooks/endpoints/wh_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"events": ["user.created", "billing.invoice.paid"], "is_active": true}'

Delete Endpoint

bash 
curl -X DELETE https://api-puguh.arsaka.io/webhooks/endpoints/wh_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

View Deliveries

bash 
curl https://api-puguh.arsaka.io/webhooks/endpoints/wh_abc123/deliveries \
  -H "Authorization: Bearer YOUR_TOKEN"

Limits by Plan

PlanMax EndpointsRetry
Free33 attempts
Pro105 attempts
Business255 attempts + guaranteed delivery
EnterpriseUnlimited5 attempts + guaranteed delivery

Best Practices

  1. Always verify signatures to prevent spoofed requests
  2. Respond quickly with 200 OK and process events asynchronously
  3. Handle duplicates using delivery_id for idempotency
  4. Use HTTPS for your endpoint URL
  5. Monitor delivery failures in the dashboard
  6. Rotate secrets periodically for security

Related