Skip to content
Talki DevelopersBeta

installation.scopes_changed

POST

An account reconnects your app with a different set of scopes. A reconnect with the same scopes sends nothing. Sent to your OAuth app’s events URL only.

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters”
X-Talki-Signature
required
string

t=<unix seconds>,v1=<hex HMAC-SHA256>, the HMAC computed over <t>.<raw body> with the signing secret. During a secret rotation it carries one v1 per secret: accept the request if any matches.

X-Talki-Event
required
string

The event type, as in type.

X-Talki-Delivery
required
string

The event ID, as in id.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
id
required
Id

The event’s ID, evt_ and 32 hex characters. Equal to the X-Talki-Delivery header and unchanged on a redelivery: deduplicate on it.

string
type
required
string
Allowed values: installation.scopes_changed
created_at
required
Created At

When the event was written, ISO 8601 with a +00:00 offset, possibly with microseconds. Parse it as an instant.

string format: date-time
api_version
required
Api Version

The dated contract version data is shaped for: the endpoint’s version on a webhook, the app’s on an app event.

string
account_id
required
Account Id

The Talki account the event happened on.

string
livemode
required
Livemode

false for an event from a sandbox account.

boolean
origin
required

Always null on installation events.

null
installation_id
required
Any of:
string
data
required

The event’s payload.

object
installation
required
Installation

The installation, as it is after the change.

object
object
required
Object

Always installation.

string
id
required
Id

The installation’s ID: one account’s connection to your app. The same value as installation_id on the envelope.

string
client_id
required
Client Id

Your app’s client ID.

string
account_id
required
Account Id

The Talki account that installed the app.

string
scopes
required
Scopes

The scopes the account granted, sorted.

Array<string>
status
required
Status

active, or revoked once the installation is disconnected.

string
Allowed values: active revoked
access
required
Access

suspended while the account cannot use the API, otherwise active. The grant and its tokens survive a suspension.

string
Allowed values: active suspended
livemode
required
Livemode

false for a sandbox account’s installation.

boolean
created_at
required
Any of:
string format: date-time
revoked_at
required
Any of:
string format: date-time
previous_scopes
required
Previous Scopes

The scopes granted before the reconnect, sorted. The new ones are in installation.scopes.

Array<string>
Example
{
  "id": "evt_04d8e87897db4ecab459a456ea55e754",
  "type": "installation.scopes_changed",
  "created_at": "2026-09-22T15:04:06.218734+00:00",
  "api_version": "2026-10-01",
  "account_id": "f7e39b9a-1ac8-45e4-93da-2600f17cb286",
  "livemode": true,
  "origin": null,
  "installation_id": "5d0e8a2c-7b41-4f7e-9c3a-1e2f4b6d8a90",
  "data": {
    "installation": {
      "object": "installation",
      "id": "5d0e8a2c-7b41-4f7e-9c3a-1e2f4b6d8a90",
      "client_id": "talki_cid_4Hq2mZ8rVt1LxN3pYw7KcA",
      "account_id": "f7e39b9a-1ac8-45e4-93da-2600f17cb286",
      "scopes": [
        "appointments:read",
        "calls:read"
      ],
      "status": "active",
      "access": "active",
      "livemode": true,
      "created_at": "2026-09-15T09:14:31.204518+00:00",
      "revoked_at": null
    },
    "previous_scopes": [
      "calls:read"
    ]
  }
}

Responses

Section titled “ Responses ”

2XX

Section titled “2XX”

Any 2xx acknowledges the event. Any other status, a redirect, or no answer within 10 seconds is a failure and is retried; 410 disables a webhook endpoint at once.