Webhooks Overview

To facilitate control over the app's features, LiveKit offers webhook capabilities.
Feature Overview
Users can configure a webhook to a specified URL via REST API. When the executed WebhookCommand is on the configuration list, it will trigger the webhook.
Notes
Only one webhook can be set per sdkAppId.
Ensure that the webhook URL is accessible.
Webhook Protocol
Third-party webhooks are based on HTTP/HTTPS protocols. The app backend must provide a webhook URL to the live platform, and Instant Chat uses a POST request to initiate a webhook to the app backend. When initiating a webhook, 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
 WebhookCommand
Webhook 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 webhook configuration.
2. In setting webhook 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=xxxxyyyy
RequestTime=1669872112
Sign=sha256(xxxxyyyy1669872112)=17773bc39a671d7b9aa835458704d2a6db81360a5940292b587d6d760d484061
﻿
Webhook 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.
﻿

Parameter	Meaning
SdkAppId	SDKAppId assigned by the Chat console when an app is created
WebhookCommand	Webhook 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)

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.