API reference
Webhooks
drop.media sends a signed POST to your endpoints when files are added, shared, deleted or expire, whichever way it happened: the browser, an agent, the API, email or SFTP.
Add endpoints on the Webhooks page in the app. An endpoint must be https:// and on the public internet, and an account can have up to 10. For a full walkthrough, see Run code when a file arrives.
Events
| file.created | A file is added to the library. data.file is the file object. |
| file.shared | A share link is made, in the app, with POST /files/{id}/link or with the MCP share_file tool. data.file carries that link, and data.via says how (web, api, mcp). |
| file.deleted | A file is deleted. data.file has its id, name, type, size and visibility, but no links: they no longer work. |
| file.expired | A file is removed because its expiry passed. Same data as file.deleted. |
| ping | Sent by Send test event on an endpoint's page. |
The request
Body
{
"id": "1f0c6a4e-2b7d-4c1e-9a53-0d6f3e2b8c11",
"type": "file.created",
"created_at": "2026-11-18T09:30:00+00:00",
"data": {
"file": {
"id": "q3-revenue",
"url": "https://cdn.drop.media/acme/q3-revenue.png",
"name": "q3-revenue.png",
"mime_type": "image/png",
"size": 48213,
"visibility": "public",
"source": "mcp",
"\u2026": "\u2026"
}
}
}| Drop-Eventheader | The event type, e.g. file.created. |
| Drop-Deliveryheader | The event's id. It's the same on every retry, so use it to ignore duplicates. It's also the event's id in Logs. |
| Drop-Signatureheader | t=<unix time>,v1=<signature>. See below. |
Checking signatures
Each endpoint has a signing secret (whsec_…), shown on its page. v1 is the hex HMAC-SHA256 of <t>.<raw body> with that secret. To check a request:
- Read
tandv1fromDrop-Signature. - Compute the HMAC of
t, a dot and the raw request body, before parsing it as JSON. - Compare it with
v1in constant time, and refuse timestamps more than five minutes old.
import crypto from 'node:crypto';
// header: the Drop-Signature header. rawBody: the request body as received, before parsing.
function isValid(header, rawBody, secret) {
const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? '');
if (!match) return false;
const [, t, sig] = match;
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}import hashlib, hmac, time
# header: the Drop-Signature header. raw_body: the request body as bytes, before parsing.
def is_valid(header: str, raw_body: bytes, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, sig = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit():
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, sig) and abs(time.time() - int(t)) < 300import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"fmt"
"time"
)
// header: the Drop-Signature header. body: the request body as received, before parsing.
func isValid(header string, body []byte, secret string) bool {
var t int64
var sig string
if _, err := fmt.Sscanf(header, "t=%d,v1=%s", &t, &sig); err != nil {
return false
}
mac := hmac.New(sha256.New, []byte(secret))
fmt.Fprintf(mac, "%d.", t)
mac.Write(body)
expected := hex.EncodeToString(mac.Sum(nil))
age := time.Since(time.Unix(t, 0))
return hmac.Equal([]byte(expected), []byte(sig)) && age < 5*time.Minute && age > -5*time.Minute
}require "openssl"
# header: the Drop-Signature header. raw_body: the request body as received, before parsing.
def valid_signature?(header, raw_body, secret)
t, sig = header.to_s.match(/\At=(\d+),v1=(\h{64})\z/)&.captures
return false unless t
expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{t}.#{raw_body}")
OpenSSL.fixed_length_secure_compare(expected, sig) && (Time.now.to_i - t.to_i).abs < 300
end
// $header: the Drop-Signature header. $rawBody: the request body as received, before parsing.
function isValidSignature(string $header, string $rawBody, string $secret): bool
{
if (! preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $header, $m)) {
return false;
}
$expected = hash_hmac('sha256', $m[1].'.'.$rawBody, $secret);
return hash_equals($expected, $m[2]) && abs(time() - (int) $m[1]) < 300;
}Responding and retries
- Reply with any
2xxwithin 10 seconds. Do slow work after replying. - Anything else, or no reply, is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours, then marked failed.
- Redirects aren't followed.
- Each endpoint's page lists its deliveries for a month, with the response, and can retry a failed one.
- A paused endpoint gets nothing, and events from while it was paused aren't sent later.