Webhooks Are Live: Deliver Events to Your Endpoint

Webhooks are live. Pick the events you want, point them at your webhook endpoint, and receive verified, signed notifications about activity in your account.

Event contract and delivery

Short and practical:

• Events are JSON POSTs with id, type, timestamp, version, account_id, resource, optional actor, and a data object containing event details.
• Ellipticc Drive is end-to-end encrypted. Webhook payloads do not include plaintext file contents or user secrets; for file events the data object contains only identifiers and metadata visible to the client (for example: id, mimetype, size, uploaded_at/modified_at, share_status).
• Events are versioned and delivered at-least-once. Deduplicate using id and design idempotent handlers.

Example payload:

1
{
2
  "id": "evt_01F",
3
  "type": "file.uploaded",
4
  "version": "1",
5
  "timestamp": "2026-01-16T12:34:56Z",
6
  "account_id": "acct_01F",
7
  "resource": {
8
    "type": "file",
9
    "id": "file_01F"
10
  },
11
  "actor": {
12
    "type": "user",
13
    "id": "user_01F"
14
  },
15
  "data": {
16
    "mimetype": "image/jpeg",
17
    "size": 12345,
18
    "uploaded_at": "2026-01-16T12:30:00Z",
19
    "share_status": "private"
20
  },
21
  "metadata": {
22
    "request_id": "d938d559-d31c-429f-865d-77fbcb233d52"
23
  }
24
}

Signing, replay protection, and verification

• Payloads are signed with HMAC-SHA256 over the raw body. Signature header: X-Ellipticc-Signature in the form <sig_id>=<hex>.
• Verify signature using a timing-safe comparison and reject mismatches.
• Check X-Ellipticc-Timestamp to mitigate replay attacks; allow a small clock skew (±5 minutes).

Node.js verification (raw body required):

1
const crypto = require('crypto');
2
function verify(secret, raw, header) {
3
  const [, hex] = header.split('=');
4
  const expected = crypto.createHmac('sha256', secret).update(raw).digest('hex');
5
  return crypto.timingSafeEqual(Buffer.from(hex,'hex'), Buffer.from(expected,'hex'));
6
}

Delivery and retries

• Expect a JSON POST and reply 2xx on success. Non-2xx triggers retries with exponential backoff.
• We move undeliverable events to a dead-letter list you can inspect in the dashboard.

Test and debug

• Use the dashboard’s delivery log and test-event feature to validate handlers.
• Local testing: ngrok or requestbin are useful to inspect raw payloads and headers.

Security and quotas

• Use HTTPS-only endpoints, rotate signing secrets, and verify signatures before processing.
• For very sensitive events route them to a dedicated endpoint with tighter controls.
• Unlimited plan users can set a custom signing secret (up to 64 characters) and receive up to 10,000 events/month. Contact support for custom SLAs.

Quick setup

1. Go to Dashboard → Settings → Developer → Webhooks.
2. Click Add endpoint and enter your URL.
3. Select the events you want to receive.
4. Copy the signing secret, save it securely, and enable the endpoint (send test event to ensure everything’s okay).

All webhook payloads include a signature you should verify using the signing secret. Unlimited plan users can choose a custom signing secret (up to 64 characters) and receive up to 10,000 events per month. Lower plans have safe default signing secrets and tiered event quotas.

If you need higher throughput, custom fields, or private delivery options, contact support and we will work with you.