---
title: Webhooks and applications
path: administration/webhooks-and-applications
status: published
---

Two related admin features for letting external systems integrate with ScaiDrive: **webhooks** push notifications out when things happen, and **applications** issue OAuth credentials for code that needs to call ScaiDrive APIs.

## Webhooks

Identity → Webhooks → **New webhook**. Configure:

| Field | Purpose |
|---|---|
| Name | What you call it |
| URL | Endpoint that receives POSTs |
| Events | Which event categories trigger this webhook |
| Filters | Optional — only fire for matching shares / users / IPs |
| Secret | Shared HMAC key — ScaiDrive signs each payload so you can verify |
| Headers | Optional custom headers (auth token to your endpoint, content-type override) |

### Event categories that can fire webhooks

Same set as [audit events](/docs/scaidrive/administration/audit-and-activity#event-categories): authentication, authorization, file access, file modification, sharing, admin, security, compliance.

Most webhook setups subscribe to a narrow set. Common ones:

- **`SHARING`** — your CRM wants to know when files are shared with customers.
- **`FILE_MODIFICATION`** — your analytics pipeline ingests new uploads to a specific share.
- **`SECURITY`** — your incident response platform gets a page on suspicious activity.

### Payload shape

ScaiDrive POSTs the same JSON event you see in the audit log:

```json
{
  "event_id": "evt_...",
  "timestamp": "2026-05-12T14:23:01Z",
  "category": "SHARING",
  "action": "share.member_added",
  "user_id": "usr_...",
  "resource_id": "shr_...",
  "payload": { "principal_id": "usr_...", "role": "contributor" }
}
```

Headers include `X-ScaiDrive-Event`, `X-ScaiDrive-Signature` (HMAC-SHA256 over the body, using the webhook secret), and `X-ScaiDrive-Delivery-Id`.

### Reliability

Webhooks retry on non-2xx responses with exponential backoff: 30s, 1m, 5m, 15m, 1h, 6h, 24h. After 24 hours of failure, deliveries are dropped (and a `SECURITY` event is logged). The webhook detail page shows recent deliveries with success/failure and response codes.

If your endpoint is going to be down for maintenance, **Pause** the webhook — ScaiDrive stops sending and the events queue up to a configurable limit (default 1000); resume catches up.

## Applications

OAuth client credentials for code that needs to authenticate to ScaiDrive without a human in the loop — CI pipelines, integrations, internal tools.

Identity → Applications → **New application**:

| Field | Purpose |
|---|---|
| Name | What you call this app |
| Description | Free-text for your future self |
| Redirect URIs | If the app uses OAuth authorization-code flow |
| Scopes | Allowed scopes — same as user permissions |
| Token lifetime | Default 1 hour; can be shortened for hot tokens |

On save, ScaiDrive issues:

- **Client ID** (public, can be hardcoded)
- **Client secret** (shown once, store in your secret manager)

### Flows supported

ScaiDrive delegates OAuth to ScaiKey, so the supported flows are whatever ScaiKey supports — typically:

- **Authorization Code with PKCE** — for human-in-the-loop apps (e.g., a third-party UI integrating with ScaiDrive).
- **Client Credentials** — for service-to-service calls (no human). The app gets a token using its client ID + secret, then calls the ScaiDrive API.
- **Token Exchange (RFC 8693)** — for "act on behalf of" flows. The app exchanges its own token for one bound to a specific user, including an `act` claim that lands in audit events as the `service_account`.

### Scopes

ScaiDrive scopes follow the `<resource>:<action>` pattern:

| Scope | Grants |
|---|---|
| `files:read` | List + download in any share the principal has access to |
| `files:write` | Upload, delete, rename |
| `shares:read` / `shares:write` | View / modify share membership |
| `links:create` | Create external links |
| `search:read` | Use keyword + semantic search |
| `admin:read` / `admin:write` | Admin console operations |

Add scopes by ticking them when you create the application; you can edit later. Tighten the scope to the minimum your integration actually needs.

### Rotating secrets

Identity → Applications → application detail → **Rotate secret**. Generates a new secret; the old one is invalidated after a 24-hour grace period (so you can deploy the new secret without downtime). Audit log captures the rotation.

## When to use what

| If you want to | Use |
|---|---|
| Notify your system when X happens in ScaiDrive | Webhook |
| Call ScaiDrive API from another system | Application + bearer token |
| Both | Both |
| One-off scripting by a person | Personal API key on a [service account user](/docs/scaidrive/administration/users-and-groups#service-accounts) |

## What's next

- [SIEM integration](/docs/scaidrive/administration/siem-integration) — for high-volume event export, prefer this over webhooks.
- [Audit and activity](/docs/scaidrive/administration/audit-and-activity) — webhook delivery is itself audited.