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

# Webhook Types

# Webhook Types

This page documents the webhook interfaces used for communication between MentraOS Cloud and App servers.

Webhooks are HTTP requests sent from MentraOS Cloud to your App server to manage the lifecycle of App sessions.

## BaseWebhookRequest

The base structure for all webhook requests sent to App servers.

```typescript theme={null}
interface BaseWebhookRequest extends BaseMessage {
  /** The specific type of webhook request. */
  type: WebhookRequestType;

  /** The session identifier this request pertains to. */
  sessionId: string;

  /** The user identifier this request pertains to. */
  userId: string;

  /** Timestamp string when the webhook was generated. */
  timestamp: string;
}
```

## SessionWebhookRequest

Webhook sent to initiate a new App session. Handled by [`AppServer.onSession`](/app-devs/reference/app-server#onsession-protected).

```typescript theme={null}
interface SessionWebhookRequest extends BaseWebhookRequest {
  /** Must be WebhookRequestType.SESSION_REQUEST. */
  type: WebhookRequestType.SESSION_REQUEST;

  /** The specific WebSocket URL the AppSession should connect to for this session. */
  mentraOSWebsocketUrl?: string;
}
```

**Example:**

```typescript theme={null}
// This is handled automatically by AppServer, but here's how it looks
{
  "type": "session_request",
  "sessionId": "session-123456",
  "userId": "user-789012",
  "timestamp": "2023-04-01T12:30:45Z",
  "mentraOSWebsocketUrl": "wss://api.mentra.glass/app-ws/session-123456"
}
```

When this webhook is received, your [`AppServer.onSession`](/app-devs/reference/app-server#onsession-protected) method is called with a new [`AppSession`](/app-devs/reference/app-session) instance, the `sessionId`, and the `userId`.

## StopWebhookRequest

Webhook sent to request stopping a App session. Handled by [`AppServer.onStop`](/app-devs/reference/app-server#onstop-protected).

```typescript theme={null}
interface StopWebhookRequest extends BaseWebhookRequest {
  /** Must be WebhookRequestType.STOP_REQUEST. */
  type: WebhookRequestType.STOP_REQUEST;

  /** The reason the session is being stopped. */
  reason: 'user_disabled' | 'system_stop' | 'error';
}
```

**Example:**

```typescript theme={null}
// This is handled automatically by AppServer, but here's how it looks
{
  "type": "stop_request",
  "sessionId": "session-123456",
  "userId": "user-789012",
  "timestamp": "2023-04-01T13:45:30Z",
  "reason": "user_disabled"
}
```

When this webhook is received, your [`AppServer.onStop`](/app-devs/reference/app-server#onstop-protected) method is called with the `sessionId`, `userId`, and `reason`.

## ServerRegistrationWebhookRequest

Webhook confirming successful registration of the App server with MentraOS Cloud.

```typescript theme={null}
interface ServerRegistrationWebhookRequest extends BaseWebhookRequest {
  /** Must be WebhookRequestType.SERVER_REGISTRATION. */
  type: WebhookRequestType.SERVER_REGISTRATION;

  /** Unique ID for this server registration. */
  registrationId: string;

  /** Package name of the registered App. */
  packageName: string;

  /** URLs associated with this registration. */
  serverUrls: string[];
}
```

**Example:**

```typescript theme={null}
{
  "type": "server_registration",
  "sessionId": "registration-123456",
  "userId": "system",
  "timestamp": "2023-04-01T10:00:00Z",
  "registrationId": "reg-78901234",
  "packageName": "org.company.myapp",
  "serverUrls": ["https://myapp-app.example.com/webhook"]
}
```

## SessionRecoveryWebhookRequest

Webhook sent when the cloud attempts to recover a potentially disconnected session.

```typescript theme={null}
interface SessionRecoveryWebhookRequest extends BaseWebhookRequest {
  /** Must be WebhookRequestType.SESSION_RECOVERY. */
  type: WebhookRequestType.SESSION_RECOVERY;

  /** The WebSocket URL to use for reconnection. */
  mentraOSWebsocketUrl: string;
}
```

**Example:**

```typescript theme={null}
{
  "type": "session_recovery",
  "sessionId": "session-123456",
  "userId": "user-789012",
  "timestamp": "2023-04-01T14:15:30Z",
  "mentraOSWebsocketUrl": "wss://api.mentra.glass/app-ws/session-123456"
}
```

## ServerHeartbeatWebhookRequest

Webhook sent periodically to check App server health. Requires a success response.

```typescript theme={null}
interface ServerHeartbeatWebhookRequest extends BaseWebhookRequest {
  /** Must be WebhookRequestType.SERVER_HEARTBEAT. */
  type: WebhookRequestType.SERVER_HEARTBEAT;

  /** The registration ID being checked. */
  registrationId: string;
}
```

**Example:**

```typescript theme={null}
{
  "type": "server_heartbeat",
  "sessionId": "heartbeat-123456",
  "userId": "system",
  "timestamp": "2023-04-01T14:30:00Z",
  "registrationId": "reg-78901234"
}
```

## WebhookResponse

Standard response structure App servers should return for webhook requests.

```typescript theme={null}
interface WebhookResponse {
  /** Indicates success or failure of handling the webhook. */
  status: 'success' | 'error';

  /** Optional message providing details, especially on error. */
  message?: string;
}
```

**Example Success Response:**

```typescript theme={null}
{
  "status": "success"
}
```

**Example Error Response:**

```typescript theme={null}
{
  "status": "error",
  "message": "Failed to create session: Invalid configuration"
}
```

## Type Guards

The SDK provides utility functions to check the type of webhook request:

```typescript theme={null}
// Check if a request is a session request
function isSessionWebhookRequest(request: WebhookRequest): request is SessionWebhookRequest;

// Check if a request is a stop request
function isStopWebhookRequest(request: WebhookRequest): request is StopWebhookRequest;

// Check if a request is a server registration request
function isServerRegistrationWebhookRequest(request: WebhookRequest): request is ServerRegistrationWebhookRequest;

// Check if a request is a session recovery request
function isSessionRecoveryWebhookRequest(request: WebhookRequest): request is SessionRecoveryWebhookRequest;

// Check if a request is a server heartbeat request
function isServerHeartbeatWebhookRequest(request: WebhookRequest): request is ServerHeartbeatWebhookRequest;
```

**Example (For Manual Webhook Processing):**

```typescript theme={null}
// You typically don't need to do this as AppServer handles it automatically
function processWebhook(request: WebhookRequest): WebhookResponse {
  if (isSessionWebhookRequest(request)) {
    // Handle session request
    return { status: 'success' };
  } else if (isStopWebhookRequest(request)) {
    // Handle stop request
    return { status: 'success' };
  } else {
    // Unknown request type
    return {
      status: 'error',
      message: `Unknown webhook type: ${request.type}`
    };
  }
}
```

## Webhook Flow

1. **Registration**: When your [`AppServer`](/app-devs/reference/app-server) starts, it is registered with MentraOS Cloud.
2. **Server Registration Confirmation**: MentraOS Cloud sends a [`SERVER_REGISTRATION`](/app-devs/reference/enums#webhookrequesttype) webhook to confirm registration.
3. **Heartbeat**: MentraOS Cloud periodically sends [`SERVER_HEARTBEAT`](/app-devs/reference/enums#webhookrequesttype) webhooks to check if your server is still running.
4. **Session Initialization**: When a user starts your App, MentraOS Cloud sends a [`SESSION_REQUEST`](/app-devs/reference/enums#webhookrequesttype) webhook.
5. **Session Termination**: When a user stops your App or there's a system issue, a [`STOP_REQUEST`](/app-devs/reference/enums#webhookrequesttype) webhook is sent.
6. **Session Recovery**: If MentraOS Cloud restarts or detects a potential disconnection, it may send a [`SESSION_RECOVERY`](/app-devs/reference/enums#webhookrequesttype) webhook.