Webhooks

Receive signed file lifecycle events from Beecargo on your server.

Create an endpoint

Add your public HTTPS URL in Dashboard → Settings → Webhooks. Choose the events you need, then save the signing secret shown after creation.

Events

file.ready — the safety check passed and the file can be downloaded.
file.failed — the file was blocked or the safety check could not finish.
file.expired — the file reached its expiry time.
file.authorized — a download was authorized for this file.
file.downloaded — delivery of the file finished.

Request

Verify the signature

Read the raw request body. Join the webhook ID, timestamp, and raw body with periods. Calculate HMAC-SHA256 using your signing secret, then compare it with the hexadecimal value after v1,.

beecargo-webhook-id identifies the event and can be used for idempotency.
beecargo-webhook-timestamp is the Unix timestamp used in the signature.
beecargo-webhook-signature has the form v1,HEX_DIGEST.
Reject stale timestamps and compare signatures in constant time.

Request examples

# signed = "{beecargo-webhook-id}.{beecargo-webhook-timestamp}.{rawBody}"
# Compare HMAC-SHA256(hex) to the value after "v1," in beecargo-webhook-signature.
EVENT_ID="evt_5af1..."
TIMESTAMP="1723123456"
SECRET="whsec_..."
RAW_BODY='{"id":"evt_5af1...","type":"file.ready","createdAt":"2026-08-08T13:00:00.000Z","data":{}}'
EXPECTED=$(printf '%s' "${EVENT_ID}.${TIMESTAMP}.${RAW_BODY}" | openssl dgst -sha256 -hmac "${SECRET}" | awk '{print $2}')
echo "v1,${EXPECTED}"

Retries

Return any 2xx status after saving the event. Beecargo retries failed or timed-out deliveries with exponential backoff and stops after eight attempts. Delivery order is not guaranteed, so process each event by ID.

{
  "id": "evt_5af1...",
  "type": "file.ready",
  "createdAt": "2026-08-08T13:00:00.000Z",
  "data": {
    "fileId": "file_V1StGXR8Z5",
    "shortId": "SEEDFA",
    "name": "report.pdf",
    "size": 48123,
    "mimeType": "application/pdf",
    "sharePath": "/d/SEEDFA/report.pdf"
  }
}