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

# Tailscale Webhook Setup Guide

> Configure Tailscale to deliver events to StackOne.

## Prerequisites

The connector should already be set up, with a Connector Profile and a Linked Account. See [Getting Started](https://docs.stackone.com/connectors/tailscale.md#getting-started) on the Tailscale connector page.

## Webhook subscription

StackOne creates one webhook for your whole tailnet when you connect the account, subscribed to the events you turn on in StackOne. StackOne deletes the webhook when you disconnect. You do not need to add a webhook in the Tailscale admin console.

<ul>
  <li>API Key connections need nothing more. The API access token already has the permissions of the user who generated it.</li>
  <li>OAuth 2.0 connections need the `webhooks` scope on the OAuth client. Without it, Tailscale refuses to create the webhook.</li>
</ul>

## Add the webhooks scope to the OAuth client

Select the `webhooks` scope when you create the OAuth client for StackOne. Skip this section if you connect with an API Key.

**1. Open Trust credentials**

Sign in to your [Tailscale admin console](https://console.tailscale.com/admin). Open [Trust credentials](https://console.tailscale.com/admin/settings/trust-credentials) under **Settings**, then select **Credential**.

![Trust credentials page in the Tailscale admin console with the Credential button highlighted](https://mintcdn.com/stackone-60/c0md3ZSNHpxXiWCq/connectors/tailscale/images/events-trust-credentials.png?fit=max\&auto=format\&n=c0md3ZSNHpxXiWCq\&q=85\&s=c001e16ec14fc1394209b613abb69b2a)

**2. Choose OAuth**

On the **New credential** page, select **OAuth**, then select **Continue**.

![New credential page with OAuth selected and the Continue button highlighted](https://mintcdn.com/stackone-60/c0md3ZSNHpxXiWCq/connectors/tailscale/images/events-new-credential-oauth.png?fit=max\&auto=format\&n=c0md3ZSNHpxXiWCq\&q=85\&s=35014479b43a8e84c19e9472f98adc5f)

**3. Select the webhooks scope**

On the **Scopes** step, expand **Keys** and select **Write** for **Webhooks**. **Read** is selected with it. Add the other scopes your connection needs, then select **Generate credential**.

<ul>
  <li>Write is needed because StackOne creates and deletes the webhook.</li>
</ul>

![Scopes step with Write selected for the Webhooks scope under Keys](https://mintcdn.com/stackone-60/c0md3ZSNHpxXiWCq/connectors/tailscale/images/events-webhooks-scope.png?fit=max\&auto=format\&n=c0md3ZSNHpxXiWCq\&q=85\&s=b6d7355313f316de8f175c3ff00badec)

## Available webhook events

The following Tailscale events can be enabled. Only events selected in StackOne are included in the webhook subscription, so Tailscale does not deliver the others.

**1. Test event**

Sent only when an admin tests the webhook.

<ul>
  <li>**Active Check** (`webhook.test`) — Fired when an admin sends a test event to the webhook from Tailscale.</li>
</ul>

**2. Device events**

Events related to devices (nodes) in the tailnet.

<ul>
  <li>**Device Created** (`device.created`) — Fired when a device is added to the tailnet.</li>
  <li>**Device Needs Approval** (`device.needs_approval`) — Fired when a new device is waiting for an admin to approve it. Pre-approved devices skip it.</li>
  <li>**Device Approved** (`device.approved`) — Fired when an admin approves a device.</li>
  <li>**Device Key Expiring** (`device.key_expiring`) — Fired when a device key will expire in less than one day.</li>
  <li>**Device Key Expired** (`device.key_expired`) — Fired when a device key has expired.</li>
  <li>**Device Deleted** (`device.deleted`) — Fired when a device is removed, including automatic removal of ephemeral devices.</li>
  <li>**Device Signed** (`device.signed`) — Fired when a trusted device signs a device. Tailnet Lock only.</li>
  <li>**Device Needs Signature** (`device.needs_signature`) — Fired when a device needs a signature from a trusted device. Tailnet Lock only.</li>
  <li>**Subnet Router IP Forwarding Disabled** (`device.subnet_ip_forwarding_disabled`) — Fired when a subnet router advertises routes but has IP forwarding turned off.</li>
  <li>**Exit Node IP Forwarding Disabled** (`device.exit_node_ip_forwarding_disabled`) — Fired when an exit node has IP forwarding turned off.</li>
</ul>

**3. User events**

Events related to users in the tailnet.

<ul>
  <li>**User Created** (`user.created`) — Fired when a user joins the tailnet.</li>
  <li>**User Needs Approval** (`user.needs_approval`) — Fired when a new user is waiting for an admin to approve them.</li>
  <li>**User Approved** (`user.approved`) — Fired when an admin approves a user.</li>
  <li>**User Suspended** (`user.suspended`) — Fired when a user is suspended.</li>
  <li>**User Restored** (`user.restored`) — Fired when a suspended user is restored.</li>
  <li>**User Deleted** (`user.deleted`) — Fired when a user is removed from the tailnet.</li>
  <li>**User Role Updated** (`user.role_updated`) — Fired when a user's role changes.</li>
</ul>

**4. Tailnet events**

Events related to the tailnet as a whole.

<ul>
  <li>**Policy File Updated** (`policy_file.updated`) — Fired when the tailnet policy file (ACLs) changes.</li>
  <li>**Webhook Updated** (`webhook.updated`) — Fired when the webhook is changed. Tailscale always sends it.</li>
  <li>**Webhook Deleted** (`webhook.deleted`) — Fired when the webhook is deleted. Tailscale always sends it.</li>
</ul>

## Delivery format

Details of how Tailscale delivers events to StackOne.

**1. Batched payloads**

Each request is a list of events. Tailscale can send several events in one request, and StackOne routes each event to its own handler. Every event carries its type, timestamp, tailnet name, a short message and an event-specific data object.

**2. Signature**

Tailscale signs each request with HMAC-SHA256 in the `Tailscale-Webhook-Signature` header. StackOne does not check it, because Tailscale returns the signing secret only once, when the webhook is created. The account's unique webhook URL identifies the connection instead.

**3. Retries**

Events usually arrive within a few seconds. A delivery that gets no response or a 3xx, 4xx or 5xx response is retried every hour for up to 24 hours.

## Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.