Skip to main content
The Webhook Service is an asynchronous, high-performance worker powered by Bun that reliably delivers real-time event notifications to your external endpoints. It listens to an internal Valkey queue and dispatches HTTP POST requests with cryptographic signatures, ensuring that you can securely verify the authenticity of the events.

​
Architecture

ComponentTechnology
RuntimeBun
Queue & logsValkey
User agentFluxhook/1.0

​
How it works

When a significant event occurs in Flux Drop (e.g., a file is uploaded or downloaded), a message is queued for the Webhook Service. The worker then:
  1. Constructs a standard JSON payload with the event details.
  2. Computes an HMAC SHA-256 signature using your webhook secret.
  3. Sends an HTTP POST request to your configured endpoint with a 10-second timeout.
  4. Logs the delivery attempt (success or failure) back to Valkey for audit logs.

​
Delivery headers

Every webhook request includes the following headers. We strongly recommend verifying the X-Fluxdrop-Signature to prevent spoofing and replay attacks.
HeaderDescription
User-AgentAlways Fluxhook/1.0
Content-Typeapplication/json
X-Fluxdrop-EventThe type of event (e.g., file.created)
X-Fluxdrop-DeliveryUnique UUID for this specific delivery attempt
X-Fluxdrop-TimestampUnix timestamp of the delivery attempt
X-Fluxdrop-SignatureHMAC SHA-256 signature of the payload

​
Payload structure

The body of the POST request will always follow this JSON structure: 
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "event": "file.created",
  "timestamp": "2026-06-05T12:00:00.000Z",
  "data": {
    // Event-specific data
  }
}
​
id
string
Unique identifier for the webhook payload.
​
event
string
The event type identifier.
​
timestamp
string
ISO 8601 timestamp of when the event payload was constructed.
​
data
object
The event-specific data context.

​
Supported events

The Webhook Service currently supports the following event types:

​
File events

  • file.created - Triggered when a new file is uploaded.
  • file.deleted - Triggered when a file is deleted.
  • file.downloaded - Triggered when a file download is triggered.

​
Share events

  • share.linked - Triggered when a share link is generated.
  • share.deleted - Triggered when a share link is removed.

​
Organization events

  • org.userAdded - Triggered when a new member joins the organization.
  • org.userRemoved - Triggered when a member is removed.
  • org.updated - Triggered when organization settings change.
  • org.permissionChanged - Triggered when a member’s role or permissions change.

​
Storage events

  • storage.exceeded - Triggered when your organization exceeds its storage limits.

​
Delivery logs

The service keeps a rotating log of the last 10 delivery attempts (retained for 7 days) per user in Valkey. This log tracks the endpoint, event, status code, and duration_ms to help you debug any integration issues.