Skip to content

Commit c72ece2

Browse files
MantisCloneCopilot
MantisClone
and
Copilot
authored
feat: add webhooks (#5)
Co-authored-by: Copilot <[email protected]>
1 parent 2c28470 commit c72ece2

File tree

6 files changed

+636
-506
lines changed

6 files changed

+636
-506
lines changed

‎api-features/create-requests.mdx‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
title: "Create Requests"
3+
description: "Request creation workflows and configuration for invoices and payment collection"
4+
---
5+
6+
## Overview
7+
8+
Request creation forms the foundation of Request Network operations, enabling structured payment collection through invoice generation and payment request workflows.
9+
10+
## Request Types
11+
12+
<CardGroup cols={2}>
13+
<Card title="Invoice Requests" icon="file-invoice">
14+
Traditional invoicing with payee details
15+
</Card>
16+
17+
<Card title="Payment Requests" icon="money-bill">
18+
Direct payment collection workflows
19+
</Card>
20+
</CardGroup>
21+
22+
## How It Works
23+
24+
```mermaid
25+
graph TD
26+
A[Define Request] --> B[Select Payment Network]
27+
B --> C[Configure Properties]
28+
C --> D[Store on IPFS]
29+
D --> E[Index on Blockchain]
30+
E --> F[Generate Request ID]
31+
```
32+
33+
**Creation Process:**
34+
1. **Define:** Set payee, payer, amount, and currency details
35+
2. **Configure:** Choose payment network and accepted tokens
36+
3. **Store:** Decentralized storage on IPFS
37+
4. **Index:** Blockchain indexing for discovery
38+
5. **Track:** Real-time status monitoring
39+
40+
## Request Properties
41+
42+
### Core Information
43+
- **Payee:** Request creator/recipient address
44+
- **Payer:** Payment sender address (optional)
45+
- **Amount:** Payment amount and currency
46+
- **Due Date:** Payment deadline (optional)
47+
48+
### Payment Configuration
49+
- **Payment Network:** ERC20, ETH, or specialized networks
50+
- **Accepted Tokens:** Supported payment currencies
51+
- **Conversion Settings:** Fiat-denominated crypto payments
52+
53+
## Payment Network Selection
54+
55+
<CardGroup cols={2}>
56+
<Card title="ERC20 Networks" icon="coins">
57+
USDC, USDT, DAI token payments
58+
</Card>
59+
60+
<Card title="Native Networks" icon="ethereum">
61+
ETH, MATIC, BNB direct payments
62+
</Card>
63+
</CardGroup>
64+
65+
### Supported Networks
66+
- **Mainnet:** Ethereum, Polygon, Arbitrum, Optimism
67+
- **Sidechains:** BSC, Gnosis, Fantom, Avalanche
68+
- **Testnets:** Sepolia, Mumbai for development
69+
70+
## Content Data
71+
72+
Attach additional information to requests:
73+
- **Invoice Details:** Line items, tax information
74+
- **Business Information:** Company details, terms
75+
- **Custom Metadata:** Application-specific data
76+
77+
## Used In
78+
79+
<CardGroup cols={2}>
80+
<Card title="Invoicing" href="/use-cases/invoicing">
81+
Business invoice generation
82+
</Card>
83+
84+
<Card title="Payroll" href="/use-cases/payroll">
85+
Employee payment requests
86+
</Card>
87+
</CardGroup>
88+
89+
## Implementation Details
90+
91+
See [API Reference - Create Requests](/api-reference/endpoints/create-request) for complete technical documentation.

‎api-features/query-requests.mdx‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
title: "Query Requests"
3+
description: "Request status monitoring, lifecycle management, and information retrieval"
4+
---
5+
6+
## Overview
7+
8+
Query requests provides comprehensive request status monitoring and information retrieval, enabling real-time tracking of payment requests throughout their lifecycle.
9+
10+
## Request Status Lifecycle
11+
12+
<CardGroup cols={2}>
13+
<Card title="Active States" icon="play">
14+
Created, pending, partially paid
15+
</Card>
16+
17+
<Card title="Final States" icon="check">
18+
Paid, cancelled, expired
19+
</Card>
20+
</CardGroup>
21+
22+
## How It Works
23+
24+
```mermaid
25+
graph LR
26+
A[Request ID] --> B[Query Status]
27+
B --> C[Retrieve Info]
28+
C --> D[Check Payments]
29+
D --> E[Update Status]
30+
```
31+
32+
**Query Process:**
33+
1. **Identify:** Use request ID for lookup
34+
2. **Retrieve:** Get current request information
35+
3. **Analyze:** Check payment status and history
36+
4. **Update:** Reflect latest blockchain state
37+
38+
## Status Types
39+
40+
### Request States
41+
- `created` - Request initialized and stored
42+
- `pending` - Awaiting payment completion
43+
- `paid` - Full payment received and confirmed
44+
- `cancelled` - Request cancelled by creator
45+
- `expired` - Past due date without payment
46+
47+
### Payment States
48+
- `no_payment` - No payment transactions detected
49+
- `partially_paid` - Partial payment received
50+
- `paid` - Full payment amount received
51+
- `overpaid` - Payment exceeds requested amount
52+
53+
## Query Methods
54+
55+
<CardGroup cols={2}>
56+
<Card title="Single Request" icon="magnifying-glass">
57+
Detailed status for specific request
58+
</Card>
59+
60+
<Card title="Batch Queries" icon="list">
61+
Multiple request status in one call
62+
</Card>
63+
</CardGroup>
64+
65+
### Information Retrieved
66+
- **Basic Details:** Amount, currency, participants
67+
- **Payment History:** Transaction details and confirmations
68+
- **Status Timeline:** Creation, updates, completion dates
69+
- **Network Data:** Blockchain and transaction information
70+
71+
## Real-time Monitoring
72+
73+
### Automatic Updates
74+
Combine with [Payment Detection](/api-features/payment-detection) for automatic status updates
75+
76+
### Event Integration
77+
Use [Webhooks & Events](/api-features/webhooks-events) for instant notifications
78+
79+
## Advanced Filtering
80+
81+
Filter requests by:
82+
- **Date Range:** Creation or due date periods
83+
- **Status:** Current request or payment state
84+
- **Participants:** Payee or payer addresses
85+
- **Amount Range:** Minimum and maximum values
86+
87+
## Used In
88+
89+
<CardGroup cols={2}>
90+
<Card title="Dashboard Apps" icon="chart-line">
91+
Real-time payment tracking
92+
</Card>
93+
94+
<Card title="Accounting Systems" icon="calculator">
95+
Invoice status reconciliation
96+
</Card>
97+
</CardGroup>
98+
99+
## Implementation Details
100+
101+
See [API Reference - Query Requests](/api-reference/endpoints/get-request) for complete technical documentation.

‎api-features/webhooks-events.mdx‎

Lines changed: 61 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -5,76 +5,92 @@ description: "Real-time notifications for payment lifecycle events and request s
55

66
## Overview
77

8-
Webhooks provide real-time notifications when payment and request events occur, enabling immediate response to status changes without polling.
8+
Webhooks provide real-time notifications when payment and request events occur, enabling immediate response to status changes without constant polling.
99

10-
## Supported Events
10+
## Event Categories
1111

1212
<CardGroup cols={2}>
1313
<Card title="Payment Events" icon="credit-card">
14-
Payment detected, confirmed, failed
14+
**Core events:** confirmed, partial, failed, refunded
15+
16+
Immediate notification when payments are processed or fail
17+
</Card>
18+
19+
<Card title="Processing Events" icon="spinner">
20+
**Crypto-to-fiat:** payment.processing with detailed subStatus
21+
22+
Track multi-step fiat conversion progress
1523
</Card>
16-
24+
1725
<Card title="Request Events" icon="file-invoice">
18-
Request created, updated, cancelled
26+
**Recurring:** request.recurring
27+
28+
Automatic subscription renewal generation
29+
</Card>
30+
31+
<Card title="Compliance Events" icon="shield-check">
32+
**KYC & verification:** compliance.updated, payment_detail.updated
33+
34+
User verification and bank account status changes
1935
</Card>
2036
</CardGroup>
2137

2238
## How It Works
2339

2440
```mermaid
2541
graph LR
26-
A[Event Occurs] --> B[Webhook Triggered]
27-
B --> C[HTTP POST]
28-
C --> D[Your Endpoint]
29-
D --> E[Process Event]
42+
A[Event Occurs] --> B[HMAC Signed POST]
43+
B --> C[Your Endpoint]
44+
C --> D[Verify & Process]
45+
D --> E[Return 200 OK]
3046
```
3147

32-
**Flow:**
33-
1. **Event:** Payment or request status changes
34-
2. **Trigger:** Automatic webhook activation
35-
3. **Delivery:** HTTP POST to your endpoint
36-
4. **Process:** Handle event in your application
48+
**Process:**
49+
1. **Event occurs:** Payment confirmed, request created, compliance updated
50+
2. **Secure delivery:** HMAC SHA-256 signed POST to your configured endpoint
51+
3. **Your processing:** Verify `x-request-network-signature`, update application state
52+
4. **Reliable delivery:** 3 retries (1s, 5s, 15s delays) with 5-second timeout
3753

38-
## Event Types
54+
## Key Features
3955

40-
### Payment Events
41-
- `payment.detected` - Payment transaction found
42-
- `payment.confirmed` - Payment confirmed on blockchain
43-
- `payment.failed` - Payment transaction failed
56+
### Reliability
57+
- **Idempotency support:** Use `x-request-network-delivery` header for duplicate detection
58+
- **Delivery confirmation:** Monitor `x-request-network-retry-count` header to track attempts
4459

45-
### Request Events
46-
- `request.created` - New request created
47-
- `request.updated` - Request information changed
48-
- `request.cancelled` - Request cancelled by creator
60+
### Security
61+
- **HMAC SHA-256 signatures:** Every webhook includes `x-request-network-signature` header
62+
- **HTTPS required:** Production endpoints must use secure connections
63+
- **Test webhook identification:** `x-request-network-test` header for development
4964

50-
## Webhook Configuration
65+
### Development Tools
66+
- **Portal testing:** Send test webhooks from [Request Portal](https://portal.request.network)
67+
- **ngrok integration:** Receive webhooks locally during development
68+
- **Comprehensive logging:** Request API logs all delivery failures with attempt details
5169

52-
### Endpoint Requirements
53-
- **HTTPS Only:** Secure webhook endpoints required
54-
- **Response Codes:** Return 200-299 for successful processing
55-
- **Timeout:** Respond within 30 seconds
70+
## Common Use Cases
5671

57-
### Retry Logic
58-
- **Automatic Retries:** Failed deliveries retried with backoff
59-
- **Maximum Attempts:** Up to 5 retry attempts
60-
- **Retry Schedule:** 1min, 5min, 25min, 2hr, 12hr
72+
- **Invoice systems:** Automatically mark invoices as paid when `payment.confirmed` received
73+
- **Order fulfillment:** Release goods or services immediately after payment confirmation
74+
- **Subscription management:** Handle `request.recurring` for automatic billing renewals
75+
- **Compliance workflows:** Update user permissions when `compliance.updated` shows KYC approval
76+
- **Real-time dashboards:** Display live payment status using `payment.processing` subStatus values
6177

62-
## Security Features
78+
## Implementation
6379

6480
<CardGroup cols={2}>
65-
<Card title="Signature Verification" icon="shield-check">
66-
HMAC signatures for authenticity
67-
</Card>
68-
69-
<Card title="IP Allowlisting" icon="network-wired">
70-
Restrict webhook sources
81+
<Card title="Webhook Reference" href="/api-reference/webhooks">
82+
Complete technical documentation with setup, payloads, and code examples
7183
</Card>
72-
</CardGroup>
73-
74-
## Implementation Examples
7584

76-
See EasyInvoice webhook handling for real-world integration patterns.
85+
<Card title="Implementation Examples" href="/api-reference/webhooks">
86+
Working webhook handlers with Express.js and Next.js
87+
</Card>
7788

78-
## Implementation Details
89+
<Card title="Request Portal" href="https://portal.request.network" icon="browser">
90+
Configure webhooks and test delivery
91+
</Card>
7992

80-
See [API Reference - Webhooks](/api-reference/webhooks) for complete technical documentation.
93+
<Card title="Request Scan" href="https://scan.request.network" icon="magnifying-glass">
94+
Explore payment transactions and request details
95+
</Card>
96+
</CardGroup>

0 commit comments

Comments
 (0)