ScopliDrop Webhooks
Get told the moment a member upvotes or enters one of your giveaways, and when a giveaway starts, ends or is rerolled. Post the events in a Discord channel, or receive them as signed JSON on your own server.
React to upvotes, entries and results
A webhook sends an event to a URL you choose when something happens in your server's giveaways. Your code hears about it at once, without polling.
- Reward the members who upvote your giveaways on the public Discord giveaway listing, for example with coins or a role. The upvote event is free on every plan.
- Follow entries as they come in, for a live counter or your own records.
- Act when a giveaway starts, ends or is rerolled, for example to hand the prize to the winners.
A webhook goes to Discord or to your own server
The URL you give decides what is sent.
A Discord channel webhook URL
Copy a webhook URL from a Discord channel, under Integrations, then Webhooks, in the channel settings. ScopliDrop posts each event as a message in that channel. There is no code to write and no signature to check. Members named in a message are not pinged.
Recognized URL
https://discord.com/api/webhooks/<id>/<token>Any other HTTPS URL
Your own server, a serverless function or an automation tool. ScopliDrop sends each event as a JSON POST and signs it with the secret of the webhook, so you can check that it comes from ScopliDrop.
Add a webhook in the dashboard
Any server can add a webhook for the upvote event. The other events need the Business or Enterprise plan.
- 1
In the ScopliDrop dashboard, open Developer, then Webhooks, and choose Add webhook. You need the Manage integrations permission on the server.
- 2
Give it a name, paste the destination URL and pick the events to send.
- 3
For an HTTPS endpoint, copy the signing secret. It starts with whsec_ and is shown once. If you lose it, rotate it to get a new one. The old secret stops working at once.
- 4
Use Send test to check the connection.
- A server can have up to 10 webhooks.
- The destination URL cannot be changed. To send events somewhere else, add a new webhook.
- The name and the events can be edited at any time, and a webhook can be paused. A paused webhook receives nothing, and the events it missed are not sent when it resumes.
Events and the plan each one needs
The upvote event is free on every plan. The other events are part of the Business and Enterprise plans on the ScopliDrop pricing page.
| Event | Plan | Fires when |
|---|---|---|
| giveaway.upvote.created | Free on every plan | A member upvotes one of the server's giveaways on the public listing. |
| giveaway.started | Business and Enterprise | A giveaway is announced in Discord. |
| giveaway.entry.created | Business and Enterprise | A member enters a giveaway. |
| giveaway.ended | Business and Enterprise | A giveaway ends. The giveaway in the event carries its winners. |
| giveaway.rerolled | Business and Enterprise | The winners of an ended giveaway are drawn again. The event carries the previous winners. |
The upvote event fires once per member and giveaway
A member can remove an upvote and add it again. ScopliDrop sends the event at most once per member and giveaway, for as long as the giveaway exists, so a reward is not paid twice.
If the server drops below the Business plan, the paid events stop being delivered. The webhook stays in place and the upvote event keeps working.
Every event has the same envelope
An HTTPS endpoint receives a JSON object with the fields below. What data holds depends on the event type.
| Field | Type | Description |
|---|---|---|
| id | string | The event id. It is the same on every webhook that receives the event and on every retry, so use it to deduplicate. |
| type | string | The event type. |
| api_version | string | Always v1. |
| created_at | string | When the event happened, not when it was sent. |
| server_id | string | The Discord server id. |
| data | object | The content of the event, described per type below. |
The giveaway and the entry inside an event are the objects the REST API returns. Their fields are documented once, under the giveaway object in the API reference and the entry object in the API reference.
The giveaway is read when the event is sent, so it shows the giveaway as it is at that moment. An event about a giveaway that was deleted in the meantime is not sent.
giveaway.upvote.created
A member upvotes one of the server's giveaways on the public listing.
Fields of data
| Field | Type | Description |
|---|---|---|
| giveaway | object | The giveaway that was upvoted. |
| upvote.user_id | string | The Discord id of the member who upvoted. |
| upvote.username | string | null | The username of the member. Null when ScopliDrop does not know it. |
| upvote.upvoted_at | string | When the member upvoted. |
{
"id": "evt_00000000-0000-4000-8000-0000000000e1",
"type": "giveaway.upvote.created",
"api_version": "v1",
"created_at": "2027-01-25T14:02:11.000Z",
"server_id": "100000000000000000",
"data": {
"giveaway": {
"id": "00000000-0000-4000-8000-000000000001",
"status": "active",
"prize": "Discord Nitro (1 month)",
"description": "One month of Nitro for one member.",
"image_url": null,
"winner_count": 1,
"starts_at": "2027-01-24T18:00:00.000Z",
"ends_at": "2027-01-31T18:00:00.000Z",
"end_condition": {
"type": "time"
},
"channel_id": "100000000000000001",
"message_id": "100000000000000002",
"url": "https://www.scoplidrop.com/g/EXAMPLE",
"entries_count": 128,
"participants_count": 97,
"requirements": {
"minimum_account_age_days": 30,
"require_2fa": false
},
"announcements": {
"winner_channel_id": null,
"ping_role_ids": []
},
"tasks": [
{
"type": "youtube-subscribe",
"name": "Follow on YouTube",
"required": true,
"points": 1
}
],
"winners": null,
"created_at": "2027-01-24T18:00:00.000Z"
},
"upvote": {
"user_id": "200000000000000001",
"username": "example_member",
"upvoted_at": "2027-01-25T14:02:11.000Z"
}
}
}giveaway.started
A giveaway is announced in Discord.
Fields of data
| Field | Type | Description |
|---|---|---|
| giveaway | object | The giveaway that was announced. |
{
"id": "evt_00000000-0000-4000-8000-0000000000e2",
"type": "giveaway.started",
"api_version": "v1",
"created_at": "2027-01-24T18:00:00.000Z",
"server_id": "100000000000000000",
"data": {
"giveaway": {
"id": "00000000-0000-4000-8000-000000000001",
"status": "active",
"prize": "Discord Nitro (1 month)",
"description": "One month of Nitro for one member.",
"image_url": null,
"winner_count": 1,
"starts_at": "2027-01-24T18:00:00.000Z",
"ends_at": "2027-01-31T18:00:00.000Z",
"end_condition": {
"type": "time"
},
"channel_id": "100000000000000001",
"message_id": "100000000000000002",
"url": "https://www.scoplidrop.com/g/EXAMPLE",
"entries_count": 0,
"participants_count": 0,
"requirements": {
"minimum_account_age_days": 30,
"require_2fa": false
},
"announcements": {
"winner_channel_id": null,
"ping_role_ids": []
},
"tasks": [
{
"type": "youtube-subscribe",
"name": "Follow on YouTube",
"required": true,
"points": 1
}
],
"winners": null,
"created_at": "2027-01-24T18:00:00.000Z"
}
}
}giveaway.entry.created
A member enters a giveaway.
Fields of data
| Field | Type | Description |
|---|---|---|
| giveaway | object | The giveaway that was entered. |
| entry | object | The new entry. |
{
"id": "evt_00000000-0000-4000-8000-0000000000e3",
"type": "giveaway.entry.created",
"api_version": "v1",
"created_at": "2027-01-24T18:05:12.000Z",
"server_id": "100000000000000000",
"data": {
"giveaway": {
"id": "00000000-0000-4000-8000-000000000001",
"status": "active",
"prize": "Discord Nitro (1 month)",
"description": "One month of Nitro for one member.",
"image_url": null,
"winner_count": 1,
"starts_at": "2027-01-24T18:00:00.000Z",
"ends_at": "2027-01-31T18:00:00.000Z",
"end_condition": {
"type": "time"
},
"channel_id": "100000000000000001",
"message_id": "100000000000000002",
"url": "https://www.scoplidrop.com/g/EXAMPLE",
"entries_count": 128,
"participants_count": 97,
"requirements": {
"minimum_account_age_days": 30,
"require_2fa": false
},
"announcements": {
"winner_channel_id": null,
"ping_role_ids": []
},
"tasks": [
{
"type": "youtube-subscribe",
"name": "Follow on YouTube",
"required": true,
"points": 1
}
],
"winners": null,
"created_at": "2027-01-24T18:00:00.000Z"
},
"entry": {
"id": "00000000-0000-4000-8000-000000000010",
"user_id": "200000000000000001",
"username": "example_member",
"entries": 3,
"source": "discord-embed",
"created_at": "2027-01-24T18:05:12.000Z"
}
}
}giveaway.ended
A giveaway ends. The giveaway in the event carries its winners.
Fields of data
| Field | Type | Description |
|---|---|---|
| giveaway | object | The ended giveaway, with its winners. |
{
"id": "evt_00000000-0000-4000-8000-0000000000e4",
"type": "giveaway.ended",
"api_version": "v1",
"created_at": "2027-01-31T18:00:00.000Z",
"server_id": "100000000000000000",
"data": {
"giveaway": {
"id": "00000000-0000-4000-8000-000000000001",
"status": "ended",
"prize": "Discord Nitro (1 month)",
"description": "One month of Nitro for one member.",
"image_url": null,
"winner_count": 1,
"starts_at": "2027-01-24T18:00:00.000Z",
"ends_at": "2027-01-31T18:00:00.000Z",
"end_condition": {
"type": "time"
},
"channel_id": "100000000000000001",
"message_id": "100000000000000002",
"url": "https://www.scoplidrop.com/g/EXAMPLE",
"entries_count": 412,
"participants_count": 305,
"requirements": {
"minimum_account_age_days": 30,
"require_2fa": false
},
"announcements": {
"winner_channel_id": null,
"ping_role_ids": []
},
"tasks": [
{
"type": "youtube-subscribe",
"name": "Follow on YouTube",
"required": true,
"points": 1
}
],
"winners": [
{
"position": 1,
"user_id": "200000000000000001",
"prize": "Discord Nitro (1 month)"
}
],
"created_at": "2027-01-24T18:00:00.000Z"
}
}
}giveaway.rerolled
The winners of an ended giveaway are drawn again. The event carries the previous winners.
Fields of data
| Field | Type | Description |
|---|---|---|
| giveaway | object | The giveaway with its new winners. |
| previous_winners | string[] | The Discord ids of the winners before the reroll, in draw order. |
{
"id": "evt_00000000-0000-4000-8000-0000000000e5",
"type": "giveaway.rerolled",
"api_version": "v1",
"created_at": "2027-02-01T10:00:00.000Z",
"server_id": "100000000000000000",
"data": {
"giveaway": {
"id": "00000000-0000-4000-8000-000000000001",
"status": "ended",
"prize": "Discord Nitro (1 month)",
"description": "One month of Nitro for one member.",
"image_url": null,
"winner_count": 1,
"starts_at": "2027-01-24T18:00:00.000Z",
"ends_at": "2027-01-31T18:00:00.000Z",
"end_condition": {
"type": "time"
},
"channel_id": "100000000000000001",
"message_id": "100000000000000002",
"url": "https://www.scoplidrop.com/g/EXAMPLE",
"entries_count": 412,
"participants_count": 305,
"requirements": {
"minimum_account_age_days": 30,
"require_2fa": false
},
"announcements": {
"winner_channel_id": null,
"ping_role_ids": []
},
"tasks": [
{
"type": "youtube-subscribe",
"name": "Follow on YouTube",
"required": true,
"points": 1
}
],
"winners": [
{
"position": 1,
"user_id": "200000000000000002",
"prize": "Discord Nitro (1 month)"
}
],
"created_at": "2027-01-24T18:00:00.000Z"
},
"previous_winners": [
"200000000000000001"
]
}
}Headers sent with every request
Requests to an HTTPS endpoint are a POST with these headers.
| Header | Value | Meaning |
|---|---|---|
| ScopliDrop-Signature | t=<unix seconds>,v1=<hex signature> | The time of sending and the signature of the request. |
| ScopliDrop-Event | giveaway.upvote.created | The event type, the same as type in the body. |
| ScopliDrop-Delivery | 00000000-0000-4000-8000-0000000000d1 | The id of this delivery. It stays the same when the delivery is retried. |
| User-Agent | ScopliDrop-Webhooks/1.0 | Identifies ScopliDrop as the sender. |
| Content-Type | application/json | The body is JSON. |
Verify the signature before you trust a request
Anyone who learns your URL can send requests to it. The signature proves that a request comes from ScopliDrop and that its body was not changed on the way.
- 1
Read the ScopliDrop-Signature header. It has two parts separated by a comma. t is the time of sending in Unix seconds and v1 is the signature in hexadecimal.
- 2
Build the signed string from the value of t, a dot and the raw request body exactly as you received it. Compute its HMAC-SHA256 with the signing secret as the key. Use the whole secret string, the whsec_ prefix included.
- 3
Compare your result with v1 in constant time.
- 4
Reject a request whose t is too old, for example more than five minutes. The timestamp is part of the signed string, so a captured request cannot be replayed later with a fresh one.
Node.js
import { createServer } from 'node:http';
import { createHmac, timingSafeEqual } from 'node:crypto';
// The signing secret (whsec_...), shown once when you add the webhook.
const SECRET = process.env.SCOPLIDROP_WEBHOOK_SECRET;
function verifySignature(secret, rawBody, header, toleranceSeconds = 300) {
// Header format: t=<unix seconds>,v1=<hex signature>
const parts = Object.fromEntries(
String(header ?? '')
.split(',')
.map((part) => part.split('=', 2)),
);
if (!/^\d+$/.test(parts.t ?? '') || !parts.v1) return false;
// Refuse old timestamps, so a captured request cannot be replayed later.
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSeconds) return false;
// HMAC-SHA256 over "<t>.<raw body>", keyed with the whole secret string.
const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`, 'utf8').digest();
const received = Buffer.from(parts.v1, 'hex');
return received.length === expected.length && timingSafeEqual(received, expected);
}
const seen = new Set(); // use your database in production
createServer((req, res) => {
const chunks = [];
req.on('data', (chunk) => chunks.push(chunk));
req.on('end', () => {
// The raw body, exactly as received. Never a re-serialized object.
const rawBody = Buffer.concat(chunks).toString('utf8');
if (!verifySignature(SECRET, rawBody, req.headers['scoplidrop-signature'])) {
res.writeHead(401).end();
return;
}
// Answer first, then do the work: the request times out after 10 seconds.
res.writeHead(204).end();
const event = JSON.parse(rawBody);
if (seen.has(event.id)) return; // the same event can arrive twice
seen.add(event.id);
if (event.type === 'giveaway.upvote.created') {
// reward event.data.upvote.user_id
}
});
}).listen(3000);Python
import hashlib
import hmac
import os
import time
from flask import Flask, abort, request
# The signing secret (whsec_...), shown once when you add the webhook.
SECRET = os.environ["SCOPLIDROP_WEBHOOK_SECRET"]
app = Flask(__name__)
def verify_signature(secret: str, raw_body: bytes, header: str, tolerance_seconds: float = 300) -> bool:
# Header format: t=<unix seconds>,v1=<hex signature>
parts = dict(part.split("=", 1) for part in (header or "").split(",") if "=" in part)
timestamp, signature = parts.get("t", ""), parts.get("v1", "")
if not timestamp.isdigit() or not signature:
return False
# Refuse old timestamps, so a captured request cannot be replayed later.
if abs(time.time() - int(timestamp)) > tolerance_seconds:
return False
# HMAC-SHA256 over "<t>.<raw body>", keyed with the whole secret string.
signed = timestamp.encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected.encode(), signature.encode())
@app.post("/webhooks/scoplidrop")
def scoplidrop_webhook():
# request.get_data() is the raw body, exactly as received.
if not verify_signature(SECRET, request.get_data(), request.headers.get("ScopliDrop-Signature", "")):
abort(401)
event = request.get_json()
# Deduplicate on event["id"], then hand the work to a background job
# so the answer goes out well within 10 seconds.
return "", 204Check your code against a known signature
With the secret, the timestamp and the body below, your code must produce exactly this header. The timestamp is in the past, so pass a very large tolerance for this check.
| Input | Value |
|---|---|
| Signing secret | whsec_dGVzdC12ZWN0b3Itc2VjcmV0LW5vdC1hLXJlYWwtb25l |
| Timestamp (t) | 1780000000 |
| Raw body | {"id":"evt_test","type":"ping"} |
| Expected header | t=1780000000,v1=ec4b435f084c245342948ff103216883b8dca89cdff3b634a8666fbc07280e38 |
Delivery, retries and switched off webhooks
Each event is delivered to each webhook on its own. A failed delivery is retried on a fixed schedule.
- Answer with any 2xx status within 10 seconds. Answer first and do the work afterwards. The body of your answer is ignored.
- Any other answer, a timeout or a connection error is a failed attempt. ScopliDrop tries again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours. After the eighth failed attempt the delivery is marked as failed.
- When the destination does not answer, times out or answers 408 or a 5xx status, ScopliDrop sends nothing more to that webhook for 60 seconds. Its other events wait and go out once the pause is over.
- A 429 answer is not counted as an attempt. ScopliDrop pauses the whole webhook until the time in your Retry-After header, 10 minutes at most, then tries again. A delivery that keeps getting 429 is not waited for forever. After a while each further 429 counts as a failed attempt, so a destination that only ever answers 429 is treated as failing.
- A 410 answer switches the webhook off at once. Send it when the endpoint is gone for good. A Discord webhook that was deleted in the channel is switched off the same way.
- A webhook is switched off once it has failed 30 times in a row and has been failing for at least 48 hours. Both must be true, so a short outage during a burst of events does not switch it off. One successful delivery resets the count. Fix the destination, then re-enable the webhook in the dashboard.
- Events can arrive more than once, and not always in the order they happened. Deduplicate on the event id and order by created_at.
- The dashboard shows the recent deliveries of each webhook with their result. Deliveries are kept for 14 days.
Rules for the destination URL and the secret
ScopliDrop only delivers to public HTTPS addresses, and treats the URL and the secret as credentials.
- Only https:// URLs are accepted, and events are delivered to the standard port 443 only. The URL cannot contain a username or a password.
- The host must be a domain name that resolves to public addresses. IP addresses, localhost and private network names are refused.
- Redirects are not followed. A 3xx answer is a failed attempt, so give the final URL.
- The signing secret is shown once, and the full URL is never shown again after you add the webhook. The dashboard keeps a masked URL only. Treat both as credentials. Anyone who has a Discord webhook URL can post in its channel.
- Verify the signature of every request, and keep the secret out of client side code and public repositories.
Test a webhook with the Send test button
Every webhook in the dashboard has a Send test button. It queues a test event for that webhook only.
- The test arrives within a few seconds and appears in the recent deliveries of the webhook with its result.
- An HTTPS endpoint receives the ping event below, signed like any other event.
- A Discord channel gets a short message that confirms the connection.
- ping cannot be subscribed to. Only the button sends it.
{
"id": "evt_00000000-0000-4000-8000-0000000000e0",
"type": "ping",
"api_version": "v1",
"created_at": "2027-01-24T17:30:00.000Z",
"server_id": "100000000000000000",
"data": {
"message": "This is a test event from ScopliDrop. Your webhook endpoint is connected."
}
}The API, verified tasks and plans
To read or change giveaways and coin balances from your own code, for example to pay the reward an upvote earned, read the ScopliDrop REST API reference.
To let your own app confirm that a member completed a task, read the Verified Actions developer documentation.
The upvote event is free. The other events are part of the Business and Enterprise plans, compared with the other plans on the ScopliDrop pricing page.