extern/tmate
1
0
Fork 0
mirror of https://github.com/tmate-io/tmate.git synced 2024-11-07 16:54:01 +01:00
Code Issues Packages Projects Releases Wiki Activity

Restore wiki page - appears to have been vandalised

Jeremy Davis 2024-05-22 16:44:42 +10:00
parent 4eaf3ebf63
commit 85b20a996a
1 changed files with 158 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

159
Webhooks.md

@ -1 +1,158 @@
tmate -k API_KEY -n session-name
# Webhooks
Webhooks allow you to integrate with tmate.io by receiving events.
When one of those events is triggered, a HTTP POST JSON payload is sent to the webhook's configured URL.
## Setup
To setup webhooks, insert these lines into your `~/.tmate.conf` file:
```
set-option -g tmate-webhook-url "http://example.com/tmate_events"
set-option -g tmate-webhook-userdata "some private data"
```
The `url` corresponds to the endpoint tmate should send events to, and the `userdata` value gets to be included in every event payload.
## Event payload and semantics
All events are sent with the following payload structure:
```
{
"type": "event_type",
"entity_id": "d8d1cbb2-f5d6-11e5-b8f0-888888888788",
"userdata": "some private data",
"params": {...},
}
```
The `type` denotes the event type (e.g. `session_register`), `entity_id` is the corresponding event entity (e.g. the `session_id`), `userdata` corresponds to the string from the `~/.tmate.conf` file, and `params` is a hash containing additional event data.
For each event, tmate.io sends the JSON payload to the configured endpoint, and expects a 2xx HTTP response code. On failure, it will retry sending that event 5 times maximum, sleeping 3 seconds between tries. If the maximum amount of tries is reached, the failed event is discarded, and the next event is sent over.
**You must be tolerant to receiving the same event twice**.
## Events
The following describes the different events.
### session_register
```
{
"type": "session_register",
"userdata": "some private data",
"entity_id": "d8d1cbb2-f5d6-11e5-b8f0-888888888788",
"params": {
"stoken": "gX5RFpICOE9n0tLMD0WDrOQe0",
"stoken_ro": "ro-QX35Q8ukrxz2MlDz7PewujUQ9",
"ssh_cmd_fmt": "ssh %s@ny2.tmate.io",
"web_url_fmt": "https://tmate.io/t/%s",
"reconnected": false,
"pubkey": "AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmkI6dXmASqzN6yqHjOME5unKxOhJblZY2wja6tCLY002IHvY=",
"ip_address": "74.64.123.124",
"client_version": "2.2.1"
}
}
```
The `session_register` event is sent when a new session is created **or when a session has reconnected after a network failure**.
* `entity_id` is the session id.
* `stoken` and `stoken_ro` are the read/write and readonly session tokens.
* `ssh_cmd_fmt` and `web_url_fmt` are the connection strings where `%s` must be replaced with `stoken` or `stoken_ro` depending on the desired access.
* `reconnected` is a boolean to denote if the session was created, or got reconnected. In the case of a reconnection, The `entity_id` will have the same value as the previously received `session_register` event. However, the connection strings may be different as the SSH server might be different. However the tokens will remain the same. You may assume all connected clients (see below) have left the session when receiving such reconnection event.
* `pubkey` is the SSH public key of the tmate host.
* `ip_address` is the IP address of the tmate host.
* `client_version` is the client version of the tmate host.
### session_close
```
{
"type": "session_close",
"userdata": "some private data",
"entity_id": "d8d1cbb2-f5d6-11e5-b8f0-888888888788",
"params": {}
}
```
The `session_close` event is sent when the host closes the session. No reconnection may be expected at this point.
* `entity_id` is the session id.
### session_join
```
{
"type": "session_join",
"userdata": "some private data",
"entity_id": "d8d1cbb2-f5d6-11e5-b8f0-888888888788",
"params": {
"id": "76ee3600-f5dc-11e5-a64d-04018f4b2301"
"readonly": false,
"type": "web",
"identity": "76ee0360-f5dc-11e5-bed2-04018f4b2301",
"ip_address": "74.64.126.154"
}
}
```
The `session_join` event is sent when a client connects to a tmate session.
* `entity_id` is the session id.
* `id` is the client id, a UUID corresponding to that client connection.
* `readonly` is true when the client connected via the readonly token.
* `type` can be either `ssh` or `web`.
* `identity` is the SSH public key of the client when `type` is `ssh`. If `type` is `web`, the identity correspond to a meaningless UUID.
* `ip_address` is the IP address of the client.
### session_left
```
{
"type": "session_left",
"userdata": "some private data",
"entity_id": "d8d1cbb2-f5d6-11e5-b8f0-888888888788",
"params": {
"id": "76ee3600-f5dc-11e5-a64d-04018f4b2301"
}
}
```
The `session_left` event is sent when a client disconnects from a tmate session.
* `entity_id` is the session id.
* `id` is the client id.
### session_stats
```
{
"type": "session_stats",
"userdata": "sometoken",
"entity_id": "edd54332-f5da-11e5-b01e-04018f4b2301"
"params": {
"id": "76ee3600-f5dc-11e5-a64d-04018f4b2301"
"latency": {
"n": 53,
"mean": 26.11320754716981,
"stddev": 3.3262382157076864,
"median": 25,
"p90": 31,
"p99": 35
}
}
}
```
The `session_stats` event is sent to provide aggregate statistics on service quality for each client.
* `entity_id` is the session id.
* `id` is the client id. If `id` is `null`, the statistics corresponds to the tmate host.
* `latency` gives aggregate statistics on latency, measured every 10 seconds by sending a ping packet to the clients and host. If the client id is not null, the latency corresponds to the **end-to-end** latency, that is `client latency + host latency`, which is the perceived latency by the client. If the client id is `null`, the latency corresponds only to the host latency.
* `n` is the number of samples acquired. Samples are taken every 10s.
* `mean`, `stddev`, `median`, `p90` and `p99` are the mean, standard deviation, median, 90th percentile, and 99th percentile