Skip to main content
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.
CallerAllowed
Dashboard session, role=adminYes
Dashboard session, role=memberNo — 403 Admin role required
API key (sk_…)No — 403

​
Request body

​
default_callback_url
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

StatusDetail
400No fields to update — the request body contained no recognized fields.
403Admin role required, or This endpoint requires an admin dashboard session. API keys cannot access admin endpoints.
404Org settings not found.
422Invalid 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

1

Open Webhooks

From the sidebar, click Webhooks.
2

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.