feat: re-write webhooks-events.mdx page

Author: MantisClone

api-features/webhooks-events.mdx

@@ -5,76 +5,70 @@ description: "Real-time notifications for payment lifecycle events and request s
 
 ## Overview
 
-Webhooks provide real-time notifications when payment and request events occur, enabling immediate response to status changes without polling.
+Webhooks provide real-time notifications when payment and request events occur, enabling immediate response to status changes without constant polling.
 
-## Supported Events
+## Event Categories
 
 <CardGroup cols={2}>
   <Card title="Payment Events" icon="credit-card">
-    Payment detected, confirmed, failed
+    Payment confirmation, processing, failures
   </Card>
-  
+
   <Card title="Request Events" icon="file-invoice">
-    Request created, updated, cancelled
+    Recurring request generation
+  </Card>
+
+  <Card title="Compliance Events" icon="shield-check">
+    KYC status and bank account verification
+  </Card>
+
+  <Card title="Crypto-to-fiat Events" icon="exchange-alt">
+    Offramp processing and settlement
   </Card>
 </CardGroup>
 
 ## How It Works
 
 ```mermaid
 graph LR
-    A[Event Occurs] --> B[Webhook Triggered]
-    B --> C[HTTP POST]
-    C --> D[Your Endpoint]
-    D --> E[Process Event]
+    A[Payment/Request Event] --> B[Webhook Triggered]
+    B --> C[HMAC Signature]
+    C --> D[HTTP POST to Your Endpoint]
+    D --> E[Signature Verification]
+    E --> F[Process Event]
+    F --> G[Return 200 OK]
 ```
 
-**Flow:**
-1. **Event:** Payment or request status changes
-2. **Trigger:** Automatic webhook activation
-3. **Delivery:** HTTP POST to your endpoint
-4. **Process:** Handle event in your application
+**Process:**
+1. **Event occurs:** Payment confirmed, request created, compliance updated
+2. **Secure delivery:** HMAC-signed POST to your configured endpoint
+3. **Your processing:** Verify signature, update application state
+4. **Reliable delivery:** Automatic retries with exponential backoff
 
-## Event Types
+## Development Setup
 
-### Payment Events
-- `payment.detected` - Payment transaction found
-- `payment.confirmed` - Payment confirmed on blockchain
-- `payment.failed` - Payment transaction failed
+### Local Testing
+- **Portal testing:** Send test webhooks from Request Portal
+- **ngrok integration:** Receive webhooks locally during development
+- **Signature verification:** Always validate `x-request-network-signature` header
 
-### Request Events
-- `request.created` - New request created
-- `request.updated` - Request information changed
-- `request.cancelled` - Request cancelled by creator
+### Security Requirements
+- **HTTPS endpoints only** for production webhook URLs
+- **SHA-256 HMAC verification** using your webhook signing secret
+- **Return 2xx status code** for successful processing (200, 201, etc.)
 
-## Webhook Configuration
-
-### Endpoint Requirements
-- **HTTPS Only:** Secure webhook endpoints required
-- **Response Codes:** Return 200-299 for successful processing
-- **Timeout:** Respond within 30 seconds
-
-### Retry Logic
-- **Automatic Retries:** Failed deliveries retried with backoff
-- **Maximum Attempts:** Up to 5 retry attempts
-- **Retry Schedule:** 1min, 5min, 25min, 2hr, 12hr
-
-## Security Features
+## Used In
 
 <CardGroup cols={2}>
-  <Card title="Signature Verification" icon="shield-check">
-    HMAC signatures for authenticity
+  <Card title="EasyInvoice Demo" href="/use-cases/invoicing">
+    Complete webhook implementation example
   </Card>
 
-  <Card title="IP Allowlisting" icon="network-wired">
-    Restrict webhook sources
+  <Card title="Real-time Dashboards" href="/use-cases/checkout">
+    Instant payment status updates
   </Card>
 </CardGroup>
 
-## Implementation Examples
-
-See EasyInvoice webhook handling for real-world integration patterns.
-
 ## Implementation Details
 
-See [API Reference - Webhooks](/api-reference/webhooks) for complete technical documentation.
+See [API Reference - Webhooks](/api-reference/webhooks) for complete technical documentation, payload schemas, and signature verification examples.

docs.json

@@ -75,7 +75,7 @@
                 ]
               },
               {
-                "group": "Payment Types",
+                "group": "Payments",
                 "pages": [
                   "api-features/payment-types-overview",
                   "api-features/standard-payments",