Overview
The connection webhook allows your application server to approve or reject a sign-in when a client initiates a WebSocket connection.
Before establishing the connection, the IM Server calls your application server. The connection is allowed when your server returns pass; otherwise, it is rejected.
Request
Webhook authentication: This API validates request headers. See Authentication.
Execution timing: This webhook runs during connection authentication. Your application server's response time directly affects connection latency.
Decision rule: The connection is allowed only when your application server responds with HTTP 200 and
result=pass(case-insensitive). All other responses reject the connection.
Request Headers
| Parameter | Data Type | Required | Description | |
|---|---|---|---|---|
| appkey | string | Yes | Application appkey. | |
| nonce | string | Yes | Random string. | |
| timestamp | string | Yes | Timestamp in milliseconds. | |
| signature | string | Yes | Signature calculated as sha1(app_secret + nonce + timestamp). | |
| Content-Type | string | Yes | Must be application/json. |
Request Parameters
| Parameter | Data Type | Required | Description | |
|---|---|---|---|---|
| user_id | string | Yes | ID of the connecting user, parsed from the token. Maximum length: 32 characters. | |
| connect_time | int64 | Yes | Connection time as a timestamp in milliseconds. | |
| sdk_version | string | No | Client SDK version from the connection request's x-version header. Maximum length: 20 characters. | |
| platform | string | No | Platform identifier from the connection request's x-platform header. Maximum length: 20 characters. | |
| device | string | No | Device information from the connection request's x-device header. Maximum length: 128 characters. | |
| device_id | string | No | Device ID from the connection request's x-deviceid header. Maximum length: 256 characters. | |
| client_ip | string | No | Client IP address from the connection request's x-clientip header. If empty, the source address of the request is used. Maximum length: 50 characters. | |
| ext | object | No | Additional headers. All headers other than x-version, x-platform, x-device, x-deviceid, and x-clientip are included in this field. |
Request Example
POST /apigateway/webhooks/connect/login HTTP/1.1
appkey: appkey
signature: 2e639ae3600a4sdff61fb88b76f485b
nonce: nonce
timestamp: 1672568121910
Content-Type: application/json
{
"user_id": "u_1001",
"connect_time": 1713600000000,
"sdk_version": "1.2.0",
"platform": "Web",
"device": "Chrome",
"device_id": "browser-uuid-001",
"client_ip": "127.0.0.1",
"ext": {
"x-appkey": "appkey",
"x-token": "xxx.yyy.zzz",
"origin": "https://example.com"
}
}
Response Example
{
"result": "pass"
}
Response Parameters
| Parameter | Data Type | Required | Description | |
|---|---|---|---|---|
| result | string | Yes | Connection decision. pass allows the connection; any other value rejects it. |