Update org settings

Update fields on the organization’s settings document. Only fields you include in the body are changed.

PATCH /api/v2/org/settings

Permissions

Updating settings requires an admin role on a dashboard session. Members and API-key auth are rejected with 403.

Caller	Allowed
Dashboard session, `role=admin`	Yes
Dashboard session, `role=member`	No — `403 Admin role required`
API key (`sk_…`)	No — `403`

Request body

string

URL Tumban will use when a scan is submitted without an explicit callback_url. Both http and https are accepted (prefer https in production). Setting it once removes the need to send callback_url on every request.The host must resolve to a public address. The URL is rejected with 422 when the safety check fails — a disallowed scheme, a missing host, a DNS-resolution failure, or a private/internal/reserved address range (RFC1918, loopback, link-local, multicast, CGNAT) — to defend against SSRF.

Response

Returns the updated org settings document. See Get org settings for the field reference.

Example

curl -X PATCH https://api-v2.tumban.com/api/v2/org/settings \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{"default_callback_url": "https://your-app.example/webhooks/tumban"}'

{
  "org_id": "org_2abc...",
  "default_callback_url": "https://your-app.example/webhooks/tumban",
  "total_scans_completed": 1284,
  "total_scans_dropped": 7,
  "created_at": "2026-01-15T08:32:11.234567+00:00",
  "updated_at": "2026-04-29T12:34:56.654321+00:00"
}

Errors

Status	Detail
400	`No fields to update` — the request body contained no recognized fields.
403	`Admin role required`, or `This endpoint requires an admin dashboard session. API keys cannot access admin endpoints.`
404	`Org settings not found`.
422	`Invalid callback URL: <reason>` — `default_callback_url` failed the safety check. `<reason>` varies: disallowed scheme, missing host, DNS-resolution failure, or a private/internal/reserved address.

Using the dashboard

Open Webhooks

From the sidebar, click Webhooks.

Set the default callback URL

In the Default Callback URL tile, enter your webhook URL in the URL field (placeholder https://your-app.example/webhook) and click Save.Tumban rejects URLs that target private or internal addresses. The dashboard surfaces the error inline before submitting: “This URL targets a private/internal address. Webhooks must use a public URL.” The server’s check is authoritative.

The Default Callback URL controls are visible to all members, but the underlying endpoint is admin-only — a non-admin who clicks Save gets a 403.

Get started

Core concepts

API reference

Webhooks

Reference

Update org settings

Permissions

Request body

Response

Example

Errors

Using the dashboard

​Permissions

​Request body

​Response

​Example

​Errors

​Using the dashboard

Permissions

Request body

Response

Example

Errors

Using the dashboard