P
PUGUH
EN Get Started

Webhooks

Webhook memungkinkan aplikasi Anda menerima notifikasi HTTP real-time ketika event terjadi di PUGUH.

Cara Kerja Webhook

  1. Anda mendaftarkan endpoint URL di PUGUH
  2. Anda berlangganan event type tertentu
  3. Ketika event terjadi, PUGUH mengirim HTTP POST ke endpoint Anda
  4. Server Anda memproses payload dan merespons dengan 200 OK

Tipe Event

PUGUH memancarkan event dari semua modul infrastruktur:

Event Identity

EventDeskripsi
user.createdPengguna baru terdaftar
user.updatedProfil pengguna diubah
user.deletedAkun pengguna dihapus
auth.loginPengguna berhasil login
auth.logoutPengguna logout
auth.password_changedPassword diubah
auth.mfa_enabledMFA diaktifkan

Event Organization

EventDeskripsi
organization.createdOrganisasi baru dibuat
organization.updatedPengaturan organisasi diubah
member.invitedAnggota diundang
member.joinedAnggota menerima undangan
member.removedAnggota dihapus
member.role_changedRole anggota diperbarui

Event Billing

EventDeskripsi
billing.subscription.createdSubscription baru dimulai
billing.subscription.updatedPaket diubah
billing.subscription.cancelledSubscription dibatalkan
billing.invoice.paidPembayaran invoice diterima
billing.invoice.overduePembayaran melewati tenggat

Membuat 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"
  }'

Respons:

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

secret hanya ditampilkan sekali saat pembuatan. Simpan dengan aman untuk verifikasi tanda tangan.

Payload Webhook

Setiap pengiriman mengirimkan request JSON POST:

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"
}

Header

HeaderDeskripsi
Content-Typeapplication/json
X-Puguh-SignatureTanda tangan HMAC-SHA256
X-Puguh-Delivery-IDIdentifier pengiriman unik
X-Puguh-EventTipe event (mis. user.created)

Memverifikasi Tanda Tangan

Selalu verifikasi header X-Puguh-Signature untuk memastikan request berasal dari 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));
}

Kebijakan Retry

Jika endpoint Anda mengembalikan status non-2xx, PUGUH mencoba ulang dengan exponential backoff:

PercobaanJeda
Retry ke-11 menit
Retry ke-25 menit
Retry ke-330 menit
Retry ke-42 jam
Retry ke-512 jam

Setelah 5 percobaan gagal, pengiriman dipindahkan ke dead letter queue. Anda dapat melakukan retry secara manual dari dashboard atau API.

Mengelola Endpoint

Daftar Endpoint

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

Perbarui 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}'

Hapus Endpoint

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

Lihat Pengiriman

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

Batas per Paket

PaketMaks EndpointRetry
Free33 percobaan
Pro105 percobaan
Business255 percobaan + guaranteed delivery
EnterpriseUnlimited5 percobaan + guaranteed delivery

Praktik Terbaik

  1. Selalu verifikasi tanda tangan untuk mencegah request palsu
  2. Respons dengan cepat menggunakan 200 OK dan proses event secara asinkron
  3. Tangani duplikat menggunakan delivery_id untuk idempotency
  4. Gunakan HTTPS untuk URL endpoint Anda
  5. Pantau kegagalan pengiriman di dashboard
  6. Rotasi secret secara berkala untuk keamanan

Terkait