Promote your project here for maximum visibility.
Vote postback API
Receive a real-time HTTP POST callback on your own server whenever someone votes for your project.
How it works
When you submit or edit a project, you can provide an optional vote postback URL. Every time a vote is successfully recorded, Votekicker will send a JSON payload to that URL. This is useful for updating leaderboards, granting in-app rewards, or synchronizing vote counts with your own database.
Setting your postback URL
Go to Submit a project or open an existing project in My projects and expand the Advanced: vote postback URL section. Enter a publicly reachable HTTPS URL and save your changes. Votekicker will begin sending postbacks immediately. If signature verification is enabled on the server, your postback secret is also shown in that section.
Vote URL format
Shareable vote links support an optional
userId path parameter:https://votekicker.com/vote/:slug/:userId?
:userId is forwarded in the postback payload as userId. This lets you attribute votes to a specific user, campaign, or referral code on your side. If the vote URL does not include a userId, the payload will contain null.Request format
POST https://your-project.com/api/votekicker-postback
Content-Type: application/json
User-Agent: Votekicker-Postback/1.0
X-Votekicker-Signature: sha256=abc123...
{
"userId": "referral-123"
}Payload fields
| Field | Type | Description |
|---|---|---|
| userId | string | null | The optional userId from the vote URL (/vote/:slug/:userId), or null when not provided. |
Signature verification (optional)
Every request includes an
X-Votekicker-Signature header. The value is sha256=<hex> where the hex string is an HMAC-SHA256 of the raw JSON request body, using a per-project secret derived from your project ID. Verifying this signature is optional — if you do not check it, the payload is still useful as an informational webhook. You can find the secret in the Advanced: vote postback URL section when editing your project.// Node.js / Express example
import { createHmac } from 'node:crypto';
const secret = process.env.VOTEKICKER_SECRET;
app.post('/api/votekicker-postback', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-votekicker-signature'];
const hmac = createHmac('sha256', secret).update(req.body).digest('hex');
const expected = `sha256=${hmac}`;
if (signature !== expected) {
return res.sendStatus(401);
}
const payload = JSON.parse(req.body);
console.log('Verified vote from', payload.userId);
res.sendStatus(200);
});Response expectations
Your endpoint should respond as quickly as possible. Votekicker considers any HTTP 2xx status code a success. Non-2xx responses are logged but not retried. Timeouts and network errors are also logged but not retried.
Security notes
The postback payload is sent over HTTPS when your URL uses HTTPS. If you want to prevent forged requests, verify the
X-Votekicker-Signature header before acting on a postback. The userId is supplied by the vote URL, so validate it on your server before using it.Rotating your secret
If you suspect your secret has been leaked, you can rotate it at any time. Open your project in the editor, expand the Advanced: vote postback URL section, and click Rotate secret. You will get a new secret to use. Old postbacks in flight may still use the previous secret, so your receiver should support a brief grace period or accept both versions during rotation.