Events: `consent_request.status_changed` & `client_id_request.status_changed`

Two events that together track the OAuth onboarding dance between InboxKit, the customer, and Google Workspace or Microsoft 365 admin consoles.

🔗 For the shared HTTP contract, headers, signature verification, and retry logic, see the Webhook Integration & Signature Verification page.

Why both events are on one page

consent_request.status_changed and client_id_request.status_changed are the two halves of the OAuth onboarding flow for new mailboxes. They share the same status enum, the same lifecycle, and are typically handled by the same piece of your code. Documenting them together makes the flow clearer.

Event	What it tracks	Platforms
`consent_request.status_changed`	The customer opening and completing an OAuth consent URL to authorize InboxKit to access their workspace	Google Workspace & Microsoft 365
`client_id_request.status_changed`	The customer adding a specific Google OAuth Client ID to their Google Workspace Admin Console (domain-wide delegation)	Google Workspace only

Shared status lifecycle

Both events use the same enum. Happy path runs left-to-right:

queued → pending → processing → completed
                              ↘ failed
                              ↘ errored
                              ↘ cancelled

Status	What it means
`queued`	Request created, waiting to be picked up by the worker.
`pending`	Worker has picked it up; the URL / instructions are ready for the customer. Surface this to your user.
`processing`	InboxKit is verifying completion (polling Google/Microsoft APIs).
`completed`	✅ Successfully finished. Onboarding can proceed.
`failed`	The request failed for a reason we can explain (e.g. permissions). Check `status_text` / `status_reason`.
`errored`	The request errored unexpectedly. Check `status_text` / `status_reason`.
`cancelled`	The customer or an admin cancelled the request.

Headers (reminder)

POST /your-path HTTP/1.1
Content-Type: application/json
User-Agent: InboxKit-Webhook/1.0
X-InboxKit-Event: consent_request.status_changed   # or client_id_request.status_changed
X-InboxKit-Timestamp: 2024-01-10T17:05:00.000Z
X-InboxKit-Signature: sha256=<hex>

`consent_request.status_changed`

When it fires

When a customer needs to grant InboxKit OAuth consent to operate on their Google Workspace or Microsoft 365 tenant, InboxKit creates a consent_request. This event fires whenever that request's status changes — from the moment it's queued, through pending (the customer has a URL to open), to completed/failed.

Payload envelope

{
  "event": "consent_request.status_changed",
  "timestamp": "<ISO 8601 UTC>",
  "team_id": "<your team uid>",
  "team_name": "<your team name>",
  "data": {
    "consent_request": { /* see fields below */ },
    "metadata": { /* see fields below */ }
  }
}

`data.consent_request` fields

Every field InboxKit sends in a consent_request.status_changed webhook is listed below.

Field	Type	Nullable	Description
`uid`	string	no	Unique, stable identifier for this consent request. Use as idempotency key.
`status`	enum	no	New status. See the shared lifecycle table above.
`previous_status`	string \| null	yes	Previous status before this transition.
`consent_url`	string	no	The URL the customer needs to open to grant consent. Valid while `status` is `pending`.
`status_text`	string	no (may be empty)	Human-readable short status message.
`status_reason`	string	no (may be empty)	Machine-friendly reason code for failures (e.g. `user_denied`, `scope_mismatch`).
`retry_count`	integer	no	How many times InboxKit has retried this request.
`max_retries`	integer	no	Retry cap before the request goes terminal.
`completed_at`	ISO 8601 \| null	yes	When the request reached a terminal state (`completed`, `failed`, `errored`, `cancelled`).

`data.metadata` fields

Field	Type	Description
`updated_at`	ISO 8601	When the consent request document was last updated.
`workspace_id`	string	Internal workspace identifier.
`mailbox_id`	string	Internal identifier of the mailbox the consent request is for.

UX tip

When you receive status: "pending" with a consent_url, surface that URL to your end user immediately — that's the signal that they need to click through the Google / Microsoft consent screen. A typical pattern is:

Show a "Waiting for OAuth consent" banner with a "Open consent page" button linking to data.consent_request.consent_url.

When a status: "completed" event arrives for the same uid, hide the banner and move on to the next onboarding step.

If status: "failed" / errored, show status_text to the user so they know what went wrong.

`client_id_request.status_changed`

When it fires

For Google Workspace mailboxes, InboxKit needs the customer to add a specific OAuth Client ID to their Google Workspace Admin Console (Security → API controls → Domain-wide delegation). This request exists while that setup is in progress, and this event fires whenever its status changes.

Google-only. There is no Microsoft equivalent of this flow. If you only integrate with Microsoft 365 mailboxes, you will never see this event.

Payload envelope

{
  "event": "client_id_request.status_changed",
  "timestamp": "<ISO 8601 UTC>",
  "team_id": "<your team uid>",
  "team_name": "<your team name>",
  "data": {
    "client_id_request": { /* see fields below */ },
    "metadata": { /* see fields below */ }
  }
}

`data.client_id_request` fields

Every field InboxKit sends in a client_id_request.status_changed webhook is listed below.

Field	Type	Nullable	Description
`uid`	string	no	Unique, stable identifier for this client-id request. Use as idempotency key.
`status`	enum	no	New status. See the shared lifecycle table above.
`previous_status`	string \| null	yes	Previous status before this transition.
`domain_name`	string	no	The Google Workspace domain the Client ID is being added to.
`client_id`	string	no	The Google OAuth Client ID that needs to be (or was) added — e.g. `1234567890-abcdefgh.apps.googleusercontent.com`.
`status_text`	string	no (may be empty)	Human-readable short status message.
`status_reason`	string	no (may be empty)	Machine-friendly reason code for failures.
`retry_count`	integer	no	How many times InboxKit has retried this request.
`max_retries`	integer	no	Retry cap before the request goes terminal.
`completed_at`	ISO 8601 \| null	yes	When the request reached a terminal state.

`data.metadata` fields

Field	Type	Description
`updated_at`	ISO 8601	When the client-id request document was last updated.
`workspace_id`	string	Internal workspace identifier.

UX tip

When status becomes pending and you have a client_id, surface instructions to the customer along the lines of:

"Please add this OAuth Client ID <client_id> to Security → API controls → Domain-wide delegation in your Google Workspace Admin Console."

Then wait for the completed event to proceed.

Example receiver (Node.js)

Examples

Use the selector on the right-hand side to see different realistic transitions. Examples are tagged by event type.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Events: OAuth Consent & Client ID Changes

Events: `consent_request.status_changed` & `client_id_request.status_changed`

Why both events are on one page

Shared status lifecycle

Headers (reminder)

`consent_request.status_changed`

When it fires

Payload envelope

`data.consent_request` fields

`data.metadata` fields

UX tip

`client_id_request.status_changed`

When it fires

Payload envelope

`data.client_id_request` fields

`data.metadata` fields

UX tip

Example receiver (Node.js)

Examples

Request

Responses

Events: OAuth Consent & Client ID Changes

Events: consent_request.status_changed & client_id_request.status_changed#

Why both events are on one page#

Shared status lifecycle#

Headers (reminder)#

consent_request.status_changed#

When it fires#

Payload envelope#

data.consent_request fields#

data.metadata fields#

UX tip#

client_id_request.status_changed#

When it fires#

Payload envelope#

data.client_id_request fields#

data.metadata fields#

UX tip#

Example receiver (Node.js)#

Examples#

Request

Responses

Events: `consent_request.status_changed` & `client_id_request.status_changed`

Why both events are on one page

Shared status lifecycle

Headers (reminder)

`consent_request.status_changed`

When it fires

Payload envelope

`data.consent_request` fields

`data.metadata` fields

UX tip

`client_id_request.status_changed`

When it fires

Payload envelope

`data.client_id_request` fields

`data.metadata` fields

UX tip

Example receiver (Node.js)

Examples