Files And Retention

Hooksbase stores file uploads from form and email ingest as separate file objects so downstream consumers can download them without re-reading the original raw message body. Files are delivery-adjacent, not a standalone document store.

File model

Files are uploaded when the project's fileStorageBytes quota is greater than zero. In practice that means:

  • form and email ingest can attach file objects to a delivery
  • each stored file is tracked separately from the delivery row
  • payload JSON includes fileRef: { key, url } entries when a file object exists
  • free-tier projects keep metadata only and never upload the file content

Limits today:

  • per-file limit: 15 MB
  • per-ingest total: 50 MB

Auth model

  • Name
    Signed download URL
    Description

    GET /v1/files/{signedToken} is public. The signed token carries authority and does not require a project API key.

  • Name
    Public API
    Type
    project API key
    Description

    GET /v1/webhooks/{webhookId}/deliveries/{deliveryId}/files/{index} is the durable authenticated download route.

  • Name
    Dashboard
    Description

    Delivery body previews refresh stale fileRef.url values so the UI can keep downloading attachments after the original signed URL expires.

Signed URLs and authenticated download

Signed URLs are convenience links, not permanent identifiers:

  • fileRef.url is HMAC-signed and valid for 7 days from issuance
  • the public signed route returns 404 when the token is invalid, expired, or the underlying object is gone
  • the authenticated delivery-file route (under /v1/webhooks/{webhookId}/deliveries/{deliveryId}/files/{index}) stays available as long as the file object still exists and the project API key has access to the webhook

Use the signed URL for short-lived app flows (email recipients, browser previews) and the authenticated route for durable operator or backend tooling. The dashboard automatically re-issues fresh signed URLs when it renders a delivery, so stale fileRef.url values in persisted JSON do not need to block the UI.

Download from a signed URL

curl "https://api.hooksbase.com/v1/files/file_token_..."

Download with a project key

curl https://api.hooksbase.com/v1/webhooks/wh_123/deliveries/del_123/files/0 \
  -H "Authorization: Bearer swk_..." \
  --output attachment.bin

Retention and replay behavior

Files follow the same retention mindset as payload objects:

  • stored file bytes count against project and webhook file-storage quota
  • maintenance prunes expired file objects using the effective payload retention window
  • deletion is blocked while unre-driven DLQ rows still depend on the source delivery
  • replay deliveries share the source file objects instead of re-uploading them

This is why files are documented here with retention rather than as a generic media-management feature. They exist to support delivery workflows.

  • GET /v1/files/{signedToken}
  • GET /v1/webhooks/{webhookId}/deliveries/{deliveryId}/files/{index}
  • GET /v1/deliveries/{id}
  • GET /v1/dlq/{id}

Common mistakes

  • Treating fileRef.url as a permanent stable URL.
  • Assuming free-tier projects persist file content instead of metadata only.
  • Expecting replay to mint brand-new file objects instead of reusing the original ones.
  • Using Hooksbase file storage as a general-purpose asset bucket outside the delivery lifecycle.

Was this page helpful?