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

# Update org settings

> Update the organization's default callback URL.

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

```http theme={null}
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

<ParamField body="default_callback_url" type="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.
</ParamField>

## Response

Returns the updated org settings document. See
[Get org settings](/api/org/get-settings) for the field reference.

## Example

```bash theme={null}
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"}'
```

```json theme={null}
{
  "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

<Steps>
  <Step title="Open Webhooks">
    From the sidebar, click **Webhooks**.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  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`.
</Note>