Webhooks

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 %[email protected]",
    "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.