ScopliDrop Developer Docs

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.

Signed with HMAC-SHA256Retried up to 7 timesUpvote event free on every plan
What they are for

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.
Destinations

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.

Setup

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. 1

    In the ScopliDrop dashboard, open Developer, then Webhooks, and choose Add webhook. You need the Manage integrations permission on the server.

  2. 2

    Give it a name, paste the destination URL and pick the events to send.

  3. 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. 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

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.

EventPlanFires when
giveaway.upvote.createdFree on every planA member upvotes one of the server's giveaways on the public listing.
giveaway.startedBusiness and EnterpriseA giveaway is announced in Discord.
giveaway.entry.createdBusiness and EnterpriseA member enters a giveaway.
giveaway.endedBusiness and EnterpriseA giveaway ends. The giveaway in the event carries its winners.
giveaway.rerolledBusiness and EnterpriseThe 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.

Payloads

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.

FieldTypeDescription
idstringThe event id. It is the same on every webhook that receives the event and on every retry, so use it to deduplicate.
typestringThe event type.
api_versionstringAlways v1.
created_atstringWhen the event happened, not when it was sent.
server_idstringThe Discord server id.
dataobjectThe 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

FieldTypeDescription
giveawayobjectThe giveaway that was upvoted.
upvote.user_idstringThe Discord id of the member who upvoted.
upvote.usernamestring | nullThe username of the member. Null when ScopliDrop does not know it.
upvote.upvoted_atstringWhen 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

FieldTypeDescription
giveawayobjectThe 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

FieldTypeDescription
giveawayobjectThe giveaway that was entered.
entryobjectThe 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

FieldTypeDescription
giveawayobjectThe 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

FieldTypeDescription
giveawayobjectThe giveaway with its new winners.
previous_winnersstring[]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

Headers sent with every request

Requests to an HTTPS endpoint are a POST with these headers.

HeaderValueMeaning
ScopliDrop-Signaturet=<unix seconds>,v1=<hex signature>The time of sending and the signature of the request.
ScopliDrop-Eventgiveaway.upvote.createdThe event type, the same as type in the body.
ScopliDrop-Delivery00000000-0000-4000-8000-0000000000d1The id of this delivery. It stays the same when the delivery is retried.
User-AgentScopliDrop-Webhooks/1.0Identifies ScopliDrop as the sender.
Content-Typeapplication/jsonThe body is JSON.
Signature

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. 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. 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. 3

    Compare your result with v1 in constant time.

  4. 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.

Verify against the raw bytes of the body. If your framework parses the JSON and you serialize it again, the bytes change and the signature no longer matches.

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 "", 204

Check 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.

InputValue
Signing secretwhsec_dGVzdC12ZWN0b3Itc2VjcmV0LW5vdC1hLXJlYWwtb25l
Timestamp (t)1780000000
Raw body{"id":"evt_test","type":"ping"}
Expected headert=1780000000,v1=ec4b435f084c245342948ff103216883b8dca89cdff3b634a8666fbc07280e38
Delivery

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.
Security

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.
Testing

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."
  }
}
Related docs

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.