Scenarios

Run code when a file arrives

Run your own code whenever a file arrives, whichever way it came in: the browser, an agent, the API, email or SFTP. This guide posts each new file to a Slack channel.

  1. Write an endpoint that checks the signature

    drop.media signs every request with the endpoint's secret. Check the signature against the raw body before you parse it, and ignore old timestamps so a captured request can't be replayed.

    import crypto from 'node:crypto';
    import express from 'express';
    
    const app = express();
    const secret = process.env.DROP_WEBHOOK_SECRET; // whsec_…
    
    // express.raw keeps the body as received, which the signature is computed over.
    app.post('/webhooks/drop', express.raw({ type: 'application/json' }), async (req, res) => {
      const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(req.get('Drop-Signature') ?? '');
      if (!match) return res.sendStatus(400);
      const [, t, sig] = match;
      const expected = crypto.createHmac('sha256', secret).update(`${t}.${req.body}`).digest('hex');
      const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
      if (!fresh || !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) return res.sendStatus(400);
    
      const event = JSON.parse(req.body);
      if (event.type === 'file.created') {
        const { name, url, source } = event.data.file;
        await fetch(process.env.SLACK_WEBHOOK_URL, {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ text: `New file from ${source}: <${url}|${name}>` }),
        });
      }
      res.sendStatus(204);
    });
    
    app.listen(3000);
  2. Add the endpoint

    On the Webhooks page in the app, add your endpoint's URL (it must be https:// and reachable from the internet) and choose file.created. Copy its signing secret into DROP_WEBHOOK_SECRET.

  3. Send a test event

    Send test event on the endpoint's page sends a ping straight away and shows the response. Then upload a file any way you like and watch it arrive in Slack.

Make it reliable

  • Reply fast. Answer with any 2xx within 10 seconds, and do slow work in the background.
  • Expect retries. A failed delivery is retried for about two days, so the same event can arrive twice. The Drop-Delivery header is the event's id and stays the same on every retry: store it and skip ones you've seen.
  • Trace anything. The event id is also in Logs, which shows what caused the event and every delivery of it.

The full list of events and headers is in the Webhooks reference.