Webhooks and applications

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:

Event categories that can fire webhooks#

Same set as audit events: 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:

1
2
3
4
5
6
7
8
9

{
  "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:

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:

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#

What's next#

• SIEM integration — for high-volume event export, prefer this over webhooks.
• Audit and activity — webhook delivery is itself audited.