> ## Documentation Index
> Fetch the complete documentation index at: https://meta.fluxdrop.pl/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Service overview: Bun worker and Valkey queue

> Architecture of the Flux Drop Webhook Service, a Bun and Valkey worker that signs and delivers HMAC SHA-256 event notifications to external endpoints.

The **Webhook Service** is an asynchronous, high-performance worker powered by [Bun](https://bun.sh/) 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

| Component        | Technology     |
| ---------------- | -------------- |
| **Runtime**      | Bun            |
| **Queue & logs** | Valkey         |
| **User agent**   | `Fluxhook/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.

| Header                 | Description                                    |
| ---------------------- | ---------------------------------------------- |
| `User-Agent`           | Always `Fluxhook/1.0`                          |
| `Content-Type`         | `application/json`                             |
| `X-Fluxdrop-Event`     | The type of event (e.g., `file.created`)       |
| `X-Fluxdrop-Delivery`  | Unique UUID for this specific delivery attempt |
| `X-Fluxdrop-Timestamp` | Unix timestamp of the delivery attempt         |
| `X-Fluxdrop-Signature` | HMAC SHA-256 signature of the payload          |

## Payload structure

The body of the POST request will always follow this JSON structure:

```json theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "event": "file.created",
  "timestamp": "2026-06-05T12:00:00.000Z",
  "data": {
    // Event-specific data
  }
}
```

<ParamField body="id" type="string">
  Unique identifier for the webhook payload.
</ParamField>

<ParamField body="event" type="string">
  The event type identifier.
</ParamField>

<ParamField body="timestamp" type="string">
  ISO 8601 timestamp of when the event payload was constructed.
</ParamField>

<ParamField body="data" type="object">
  The event-specific data context.
</ParamField>

## 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.