[Backend] Build Webhook Setup & Configuration System (Secure, Validated, Multi-Event, Production Ready)

[abhishek-nexgen-dev]

We need to build a system where communities can create and manage webhooks.

This system allows users to:

Register webhook URLs
Select events to listen to
Set secrets for security
Define permissions
Enable/disable webhooks

👉 This is only setup/config layer, not delivery.

---

🎯 Goals

System must be:

• Secure (SSRF-safe, secret protected)
• Flexible (multi-event support)
• Scalable (multiple webhooks per community)
• Production-ready (validation + management APIs)

---

🧱 CORE FEATURES

---

1️⃣ CREATE WEBHOOK

---

Endpoint

POST /api/v1/webhooks

---

Payload

{
  "name": "Discord Notifications",
  "url": "https://discord.com/api/webhooks/xxx",
  "events": [
    "member.created",
    "event.created",
    "hackathon.created"
  ],
  "secret": "optional-secret-key",
  "permissions": ["read", "notify"]
}

---

Validations

---

URL Validation

• must be HTTPS

• valid domain

• block:

  • localhost
  • 127.0.0.1
  • internal IPs (SSRF protection)

---

Events Validation

Allowed events:

member.created
member.activated
event.created
event.updated
hackathon.created
community.approved
github.push
github.pr.opened

---

Secret Validation

• optional
• min length: 8
• must be hashed before storing

---

---

Flow

validate input
→ validate URL
→ validate events
→ hash secret
→ store webhook
→ return success

---

---

2️⃣ LIST WEBHOOKS

---

Endpoint

GET /api/v1/webhooks

---

Features

• list all webhooks for community

• pagination

• filter by:

  • active/inactive
  • event type

---

---

3️⃣ GET SINGLE WEBHOOK

---

GET /api/v1/webhooks/:id

---

---

4️⃣ UPDATE WEBHOOK

---

Endpoint

PATCH /api/v1/webhooks/:id

---

Allowed Updates

• name
• URL
• events
• permissions
• secret (re-hash)

---

---

5️⃣ DELETE WEBHOOK

---

DELETE /api/v1/webhooks/:id

---

---

6️⃣ ENABLE / DISABLE WEBHOOK

---

PATCH /api/v1/webhooks/:id/toggle

---

Purpose

• temporarily stop webhook without deleting

---

---

7️⃣ WEBHOOK TEST ENDPOINT

---

Endpoint

POST /api/v1/webhooks/:id/test

---

Purpose

• send test payload to URL
• verify integration works

---

Payload Example

{
  "event": "test",
  "message": "Webhook setup successful"
}

---

---

🔐 SECURITY (VERY IMPORTANT)

---

1. SSRF Protection

Block:

localhost
127.0.0.1
internal IP ranges

---

2. Secret Handling

• hash using SHA256 or bcrypt
• never return secret in API

---

3. Authentication

• only authenticated users
• must belong to community

---

4. Authorization (RBAC)

Only allowed roles:

CommunityOwner
Admin

---

---

🧾 DATABASE DESIGN

---

Webhook Schema

communityId
name
url
events
secretHash
permissions
active
createdBy
createdAt
updatedAt

---

Indexes

communityId
events
active

---

---

⚠️ ERROR HANDLING

---

Standard Format

{
  "success": false,
  "message": "Invalid webhook URL"
}

---

Common Errors

• invalid URL
• invalid event type
• unauthorized
• webhook not found

---

---

🧪 TESTING

---

Unit Tests

• URL validation
• event validation
• secret hashing

---

Integration Tests

• create webhook
• update webhook
• delete webhook

---

Security Tests

• SSRF attempts
• invalid input

---

---

🧨 EDGE CASES

---

invalid URL
duplicate webhook
invalid events
large payload
malicious URL

---

---

📊 OBSERVABILITY

---

Logs

• webhook created
• webhook updated
• webhook deleted

---

Metrics

webhooks created
active webhooks
failed test requests

---

---

⚙️ PERFORMANCE

---

• indexed queries
• pagination for list API

---

---

🌍 ENVIRONMENT

---

DEV
STAGING
PROD

---

---

✅ ACCEPTANCE CRITERIA

---

✔ Webhook can be created
✔ Events selection works
✔ Secret stored securely
✔ URL validation works
✔ SSRF protection active
✔ Webhook test endpoint works
✔ RBAC enforced
✔ APIs fully functional

---

🔥 FINAL SUMMARY

This system is:

Webhook configuration system (like Stripe / GitHub setup UI backend)