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.createdA file is added to the library. data.file is the file object.
file.sharedA 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.deletedA file is deleted. data.file has its id, name, type, size and visibility, but no links: they no longer work.
file.expiredA file is removed because its expiry passed. Same data as file.deleted.
pingSent 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:

  1. Read t and v1 from Drop-Signature.
  2. Compute the HMAC of t, a dot and the raw request body, before parsing it as JSON.
  3. Compare it with v1 in 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));
}

Responding and retries

  • Reply with any 2xx within 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.