Overview
When a user purchases a premium tier, Rankly delivers an HTTP POST request to your configured webhook endpoint. This allows your bot to:- β¨ Activate premium features instantly
- π Process transactions in real-time
- π Track premium user base accurately
- π― Handle both user and server-level premium
Premium webhooks are separate from vote webhooks. Ensure youβre using the correct webhook secret (
RANKLY_PREMIUM_WEBHOOK_SECRET).Webhook Delivery
Request Format
All premium purchase webhooks are delivered as POST requests with JSON payloads:Payload Structure
Field Reference
Event identifier. Always
premium_purchase for premium webhooks.Unique identifier for the transaction. Use this for deduplication and audit trails.
ISO 8601 formatted timestamp when the purchase occurred.
Discord server ID. Only present when
planType is server.Plan Types Explained
| Type | Scope | serverId |
|---|---|---|
| user | Applies to purchaserβs account across all servers | null |
| server | Applies to a specific Discord server | Discord Server ID |
Signature Verification
All incoming webhook requests must be verified using theX-Webhook-Signature header. This prevents unauthorized or spoofed requests.
Verification Steps
- Extract the
X-Webhook-Signatureheader - Stringify the JSON payload exactly as received
- Compute HMAC SHA256 using your webhook secret
- Use timing-safe comparison to validate
- Node.js
- Python
- Go
Complete Handler Implementation
Hereβs a production-ready webhook handler with signature verification, idempotency, and proper error handling:Duration Handling
Calculate expiry dates correctly based on subscription type:| Duration | Calculation | Example |
|---|---|---|
weekly | Current date + 7 days | Today + 1 week |
monthly | Current date + 1 month | Dec 25 β Jan 25 |
lifetime | Never expires | null |
Response Requirements
Your endpoint must meet these requirements for reliable webhook processing:| Requirement | Specification |
|---|---|
| Response Time | Return within 5 seconds |
| Success Status | HTTP 200 to acknowledge receipt |
| Idempotency | Handle duplicate deliveries gracefully |
| Retry Behavior | Non-2xx responses trigger retries |
Recommended Response
Idempotency & Deduplication
Always implement idempotency to handle potential duplicate deliveries:Database Schema
User Premium
Server Premium
Security Best Practices
Verify Signatures
Always validate webhook signatures using timing-safe comparison before processing any data.
Use HTTPS
Ensure your webhook endpoint uses TLS encryption to protect sensitive data in transit.
Rotate Secrets
Regenerate webhook secrets immediately if compromised via the Rankly dashboard.
Audit Trails
Maintain records of all
purchaseId values for compliance and support purposes.Validate Plan Types
Handle both
user and server plan types correctly in your activation logic.Async Processing
Process premium activation asynchronously to avoid timeout errors and improve reliability.
Troubleshooting
Webhooks not received
Webhooks not received
Cause: Endpoint not publicly accessibleSolutions:
- Verify your server is reachable from the internet
- Check firewall rules allow inbound traffic
- Ensure correct endpoint URL in Rankly dashboard
- Test with curl:
curl -X POST https://your-endpoint.com/webhook/premium
Signature verification fails
Signature verification fails
Cause: Wrong secret or payload modificationSolutions:
- Confirm youβre using
RANKLY_PREMIUM_WEBHOOK_SECRET(not vote secret) - Donβt modify the payload before verification
- Check for encoding issues (UTF-8)
- Regenerate secret if compromised
Missing serverId
Missing serverId
Cause: Expected for server-type plansSolutions:
serverIdis only present whenplanTypeisserver- Handle
nullvalue gracefully for user plans - Check payload structure matches your plan type
Duplicate activations
Duplicate activations
Cause: Missing idempotency implementationSolutions:
- Implement deduplication using
purchaseId - Record purchase IDs before activation
- Use database constraints for uniqueness
Timeout errors
Timeout errors
Cause: Processing takes too longSolutions:
- Return HTTP 200 immediately
- Process premium activation asynchronously
- Use background jobs (Bull, Celery, etc.)
- Add monitoring and error logging
Next Steps
- π Review Vote Webhooks for user engagement tracking
- π§ Set up webhook secret rotation in your infrastructure
- π Implement monitoring for failed activations
- π§ͺ Test with sandbox tier purchases before going live