Callback Overview
To facilitate control over the app's features, LiveKit offers callback capabilities.
Feature Overview
Users can configure a callback to a specified URL via REST API. When the executed CallbackCommand is on the configuration list, it will trigger the callback.
Notes
Only one callback can be set per sdkAppId.
Ensure that the callback URL is accessible.
Callback Protocol
Third-party callbacks are based on HTTP/HTTPS protocols. The app backend must provide a callback URL to the live platform, and Instant Chat uses a POST request to initiate a callback to the app backend. When initiating a callback, Chat adds the following parameters to the URL provided by the app:
Parameter | Meaning |
SdkAppId | SDKAppId assigned by the Chat console when an app is created |
CallbackCommand | Callback Command Word |
contenttype | Optional, usually set to JSON |
ClientIP | Client IP address |
OptPlatform | Client Platform, corresponding to different Platform Types, possible values include: RESTAPI (sending requests using REST API), Web (sending requests using Web SDK), Android, iOS, Windows, Mac, iPad, Unknown (sending requests using an unknown type of device) |
Security Considerations
Related security issues are as follows:
1. HTTP transmits data in plain text, and data confidentiality cannot be guaranteed. Therefore, HTTPS is recommended.
2. It's impossible to determine whether a webhook request really comes from Live.
For request source security, we provide the Webhook Authentication solution:
1. Configure the webhook URL and enable webhook use set callback configuration.
2. In setting callback authentication Token, enable authentication and configure the authentication token. Then, the signature (
Sign
) and signing timestamp (RequestTime
) will be added to the webhook request URL. The signature algorithm is Sign=sha256(TokenRequestTime).3. The app backend authenticates the webhook request. It uses SHA256 to calculate and verify the signature based on the local authentication token and the signing timestamp (
RequestTime
) in the webhook URL. The RequestTime is also checked for timeliness. If the difference between the RequestTime and the current time exceeds 1 minute, it is considered an invalid request to prevent replay attacks.Signature algorithm sample:Token=xxxxyyyyRequestTime=1669872112Sign=sha256(xxxxyyyy1669872112)=17773bc39a671d7b9aa835458704d2a6db81360a5940292b587d6d760d484061Webhook URL=URL&Sign=17773bc39a671d7b9aa835458704d2a6db81360a5940292b587d6d760d484061&RequestTime=1669872112
Common Reasons for Webhook Failures
If a webhook failure occurs, check whether the configured webhook service has a problem according to the following checklist:
Webhook Failure Symptom | Possible Reason |
Access to the webhook URL times out | 1. Live cannot complete DNS resolution. In this case, check whether the domain name is valid on the public network. For example, if the webhook host is http://notexist.com, Live cannot complete DNS resolution because this domain name does not exist. 2. Live cannot access the IP address configured in the webhook URL. In this case, check whether this IP address is accessible from the public network. For example, if the webhook host is http://10.0.0.1, Live cannot access this IP address because the domain name is a private IP address of the app. 3. The failure occurs due to the firewall policy of the app webhook service. In this case, check the firewall configuration. For example, a webhook failure occurs if the app webhook server denies all requests arriving at port 80. |
Access denied by the webhook service | Live can access the host, but a connection is not established. In this case, check whether the WebServer has started properly. For example, a webhook failure will occur when the WebServer of the app webhook server has not started or when the port configuration is incorrect. |
The HTTP return code of the webhook service is not 200 | The webhook request is successful, but the HTTP return code in the response packet is not 200. |
The webhook response packet could not be parsed | The webhook response packet is not in JSON format. |