Overview
When a user successfully votes for your bot on Rankly, an HTTP POST request is sent to your configured webhook endpoint. This enables you to:- π Grant instant rewards to voters
- π Track voting participation
- π― Build loyalty programs
- π Handle credit awards automatically
Vote webhooks are distinct from premium webhooks. Each uses a separate webhook secret (
RANKLY_VOTE_WEBHOOK_SECRET).Webhook Delivery
Request Format
Vote webhooks are delivered as JSON POST requests:Payload Structure
Field Reference
Event identifier. Always
bot_vote for vote webhooks.ISO 8601 formatted timestamp when the vote occurred.
Whether Rankly platform credits were awarded for this vote.
true if an ad blocker was detected during the vote process.Explanation if credits werenβt awarded.
null when credits were successfully awarded.Understanding Credit Awards
ThecreditsAwarded and adBlocker fields help you understand the vote context:
| Scenario | creditsAwarded | adBlocker | creditDenialReason |
|---|---|---|---|
| Successful vote, no blocker | true | false | null |
| Vote blocked by ad blocker | false | true | Ad blocker detected |
| Duplicate recent vote | false | false | Already voted recently |
Signature Verification
All webhooks include a cryptographic signature. Verify it before processing to prevent unauthorized requests:Verification Steps
- Extract
X-Webhook-Signatureheader - Stringify the JSON payload as received
- Compute HMAC SHA256 with your webhook secret
- Compare using timing-safe comparison
- Node.js
- Python
- Go
Complete Handler Implementation
Hereβs a production-ready webhook handler with verification, idempotency, and reward logic:Response Requirements
Your endpoint must meet these specifications for reliable delivery:| Requirement | Specification |
|---|---|
| Response Time | Return within 10 seconds |
| Success Status | HTTP 200 to acknowledge receipt |
| Idempotency | Handle duplicate deliveries gracefully |
| Retry Behavior | Non-2xx responses trigger retries |
Recommended Response
Idempotency & Deduplication
Implement deduplication usingvoter.userId and timestamp to prevent duplicate reward grants:
- Redis (Recommended)
- Database
- In-Memory (Dev Only)
Reward Implementation
Design your reward system based on vote behavior:Database Schema
Votes Table
Reward Log Table
Security Best Practices
Verify Signatures
Always validate webhook signatures before processing any vote data.
Use HTTPS
Ensure your webhook endpoint uses TLS encryption.
Rate Limiting
Implement rate limiting on your webhook endpoint to prevent abuse.
Async Processing
Process votes asynchronously to avoid timeout errors.
Monitor Failures
Log and monitor signature verification failures for security issues.
Rotate Secrets
Regenerate webhook secrets immediately if compromised.
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 HTTPS traffic
- Confirm endpoint URL is correct in Rankly dashboard
- Test:
curl -X POST https://your-endpoint.com/webhook/votes
Signature verification fails
Signature verification fails
Cause: Wrong secret or payload modificationSolutions:
- Ensure youβre using
RANKLY_VOTE_WEBHOOK_SECRET(not premium) - Donβt modify the payload before verification
- Check for encoding issues (UTF-8)
- Verify secret hasnβt been regenerated
Timeout errors
Timeout errors
Cause: Processing takes too longSolutions:
- Return HTTP 200 immediately
- Process reward grants asynchronously
- Use background job queue (Bull, Celery, etc.)
- Set up monitoring for long-running tasks
Duplicate rewards granted
Duplicate rewards granted
Cause: Missing idempotency implementationSolutions:
- Implement deduplication using
voter.userId:timestamp - Use Redis for high-traffic scenarios
- Add database constraints for uniqueness
- Record votes before processing rewards
creditsAwarded is always false
creditsAwarded is always false
Cause: Could be ad blocker, duplicate vote, or other restrictionsSolutions:
- Check if
adBlockerflag istruein payload - Review
creditDenialReasonfor specific cause - Still grant your own rewards for engagement
- Monitor credit denial patterns for issues
Best Practices
Next Steps
- π Review Premium Purchase Webhooks for monetization
- π Set up analytics for vote tracking
- π Design tier-based reward systems
- π§ͺ Test with sandbox votes before production