Webhooks
Webhooks Integration
Receive real-time notifications about verification events in your Discord server. Set up secure, reliable webhooks to integrate AkuWorks with your existing systems.
Quick Webhook Setup
Webhook Events
verification.success
User successfully verified
Triggered when: A user completes verification successfully
Payload includes:
- • User ID and username
- • Server ID and name
- • Verification timestamp
- • IP address and location
- • Verification method used
verification.failed
Verification attempt failed
Triggered when: A user fails verification or is blocked
Payload includes:
- • User ID (if available)
- • Server ID and name
- • Failure reason and code
- • IP address and location
- • Detection method triggered
security.alert
Security threat detected
Triggered when: High-risk activity or coordinated attack detected
Payload includes:
- • Threat type and severity
- • Server ID and name
- • Attack details and metrics
- • Recommended actions
- • Affected IP ranges
config.updated
Configuration changed
Triggered when: Server verification settings are modified
Payload includes:
- • Server ID and name
- • Changed settings
- • Previous and new values
- • User who made changes
- • Change timestamp
Webhook Configuration
Endpoint Requirements
HTTPS endpoint required
Must respond with 200 status
Response time < 5 seconds
Valid SSL certificate
Content-Type: application/json
Signature verification supported
Retry mechanism included
Rate limiting respected
Example Payload
{
"event": "verification.success",
"timestamp": "2025-01-25T10:30:00Z",
"server": {
"id": "123456789012345678",
"name": "My Discord Server"
},
"user": {
"id": "987654321098765432",
"username": "user#1234",
"discriminator": "1234"
},
"verification": {
"method": "turnstile",
"ip": "192.168.1.1",
"location": "US",
"user_agent": "Mozilla/5.0...",
"duration_ms": 1250
},
"signature": "sha256=abc123..."
}Security & Authentication
Signature Verification
All webhook payloads are signed with HMAC-SHA256 to ensure authenticity and prevent tampering.
// Verify webhook signature (Node.js example)
const crypto = require('crypto');
function verifySignature(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload, 'utf8')
.digest('hex');
return signature === `sha256=${expectedSignature}`;
}Security Best Practices
Always verify webhook signatures
Use HTTPS endpoints only
Implement rate limiting on your endpoint
Log webhook events for debugging
Handle retries gracefully
Monitoring & Debugging
Delivery Status
Successful deliveries98.5%
Failed deliveries1.5%
Average response time245ms
Recent Events
verification.success✓ 200
verification.failed✓ 200
security.alert✗ 500
Common Issues & Solutions
Webhook not receiving events
- • Check that your endpoint is accessible via HTTPS
- • Verify your webhook URL is correctly configured
- • Ensure your server responds with HTTP 200 status
- • Check firewall settings and SSL certificate
Signature verification failing
- • Verify you're using the correct webhook secret
- • Check that you're hashing the raw request body
- • Ensure consistent encoding (UTF-8)
- • Compare with our signature verification examples
High failure rate
- • Implement proper error handling and logging
- • Reduce response time (target < 2 seconds)
- • Handle temporary failures gracefully
- • Consider implementing a queue for processing