Webhooks

Embed
Preview of the card
<a href="https://forumulate.com/p/gaiadesk/docs/ref-webhooks-2"><img src="https://forumulate.com/api/public/orgs/gaiadesk/spaces/docs/pages/712f2b87-8f8a-4529-bffa-2ccfb074fb57/social-card.svg?v=3e7ae33eec8b" alt="Webhooks" width="600" height="315"></a>
WEBHOOKdesk.online

A desk came online (its signaling socket registered).

Parameters

GaiaDesk-Signaturestringheaderrequired
t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" keyed with the webhook secret>. Reject a delivery whose t is more than five minutes off, and de-duplicate by the event id.

Payload

application/json

One delivery. id is stable across retries; de-duplicate by it.

idstringrequired
typestringrequired
desk.online | desk.offline | desk.woke | job.finished | support.session.joined | support.session.ended
createdintegerrequired
dataobjectrequired
Show child parameters
deskobjectrequired
Show child parameters
desk_idstringrequired
ownerstringrequired
reasonstringrequired
reason_textstringrequired
versionstring
woke_after_msinteger
desk.woke: how long after the ring it came online.
{
  "id": "string",
  "type": "desk.online",
  "created": 0,
  "data": {
    "desk": {
      "desk_id": "string",
      "owner": "string",
      "reason": "string",
      "reason_text": "string",
      "version": "string",
      "woke_after_ms": 0
    }
  }
}

Responses

200 Any 2xx acknowledges the delivery; anything else is retried with backoff for 24 hours.
WEBHOOKdesk.offline

A desk went offline, with the reason (the reach log's).

Parameters

GaiaDesk-Signaturestringheaderrequired
t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" keyed with the webhook secret>. Reject a delivery whose t is more than five minutes off, and de-duplicate by the event id.

Payload

application/json

One delivery. id is stable across retries; de-duplicate by it.

idstringrequired
typestringrequired
desk.online | desk.offline | desk.woke | job.finished | support.session.joined | support.session.ended
createdintegerrequired
dataobjectrequired
Show child parameters
deskobjectrequired
Show child parameters
desk_idstringrequired
ownerstringrequired
reasonstringrequired
reason_textstringrequired
versionstring
woke_after_msinteger
desk.woke: how long after the ring it came online.
{
  "id": "string",
  "type": "desk.online",
  "created": 0,
  "data": {
    "desk": {
      "desk_id": "string",
      "owner": "string",
      "reason": "string",
      "reason_text": "string",
      "version": "string",
      "woke_after_ms": 0
    }
  }
}

Responses

200 Any 2xx acknowledges the delivery.
WEBHOOKdesk.woke

A desk rung through the API came online within three minutes.

Parameters

GaiaDesk-Signaturestringheaderrequired
t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" keyed with the webhook secret>. Reject a delivery whose t is more than five minutes off, and de-duplicate by the event id.

Payload

application/json

One delivery. id is stable across retries; de-duplicate by it.

idstringrequired
typestringrequired
desk.online | desk.offline | desk.woke | job.finished | support.session.joined | support.session.ended
createdintegerrequired
dataobjectrequired
Show child parameters
deskobjectrequired
Show child parameters
desk_idstringrequired
ownerstringrequired
reasonstringrequired
reason_textstringrequired
versionstring
woke_after_msinteger
desk.woke: how long after the ring it came online.
{
  "id": "string",
  "type": "desk.online",
  "created": 0,
  "data": {
    "desk": {
      "desk_id": "string",
      "owner": "string",
      "reason": "string",
      "reason_text": "string",
      "version": "string",
      "woke_after_ms": 0
    }
  }
}

Responses

200 Any 2xx acknowledges the delivery.
WEBHOOKjob.finished

A background job started through the API ended (exited, killed, or lost).

Parameters

GaiaDesk-Signaturestringheaderrequired
t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" keyed with the webhook secret>. Reject a delivery whose t is more than five minutes off, and de-duplicate by the event id.

Payload

application/json

job.finished: a background job started through the API ended. id is stable across retries.

idstringrequired
typerequired
createdintegerrequired
dataobjectrequired
Show child parameters
deskobjectrequired
Show child parameters
desk_idstringrequired
ownerstringrequired
jobobjectrequired
A background job on a desk.
Show child parameters
bystring
Who started it: the token's name, or owner for a person.
commandstringrequired
ended_at_msinteger
enforcementstring[]
How the desk enforces them, one line each, in its own words — and what it could not do here (e.g. "cgroups v2 not available: …").
exit_codeinteger
limitsJobLimits
The caps and keep-awake it runs under, as the desk applied them (keep_awake resolved against the desk's default). None from a desk before job limits, and for a job started with none.
log_bytesinteger
Bytes of output kept (current log plus its one rotated predecessor).
= 0
namestringrequired
pidinteger
reasonstring
Why it ended as it did, as a machine reads it, when the desk knows: blocked_by_os_policy — Windows Smart App Control or WDAC refused to start a program it ran (its state then says so in words).
started_at_msintegerrequired
statestringrequired
running, exited, killed, or lost (it was running when the GaiaDesk host restarted and its end could not be observed).
{
  "id": "string",
  "type": {},
  "created": 0,
  "data": {
    "desk": {
      "desk_id": "string",
      "owner": "string"
    },
    "job": {
      "by": "",
      "command": "string",
      "ended_at_ms": 0,
      "enforcement": [
        "string"
      ],
      "exit_code": 0,
      "limits": {
        "cpu_percent": 0,
        "keep_awake": true,
        "mem_mb": 0,
        "priority": "string"
      },
      "log_bytes": 0,
      "name": "string",
      "pid": 0,
      "reason": "string",
      "started_at_ms": 0,
      "state": "string"
    }
  }
}

Responses

200 Any 2xx acknowledges the delivery.
WEBHOOKsupport.session.joined

A support agent joined a customer's shared tab (the tab admitted them).

Parameters

GaiaDesk-Signaturestringheaderrequired
t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" keyed with the webhook secret>. Reject a delivery whose t is more than five minutes off, and de-duplicate by the event id.

Payload

application/json

support.session.joined / support.session.ended. id is stable across retries. Never carries the join code, the desk or the embed token.

idstringrequired
typestringrequired
support.session.joined | support.session.ended
createdintegerrequired
dataobjectrequired
Show child parameters
support_sessionobjectrequired
Show child parameters
idstringrequired
statestringrequired
waiting | joined | ended | expired
modestringrequired
view: the agent sees the shared tab. cobrowse: the agent may also point, highlight, click, scroll and type INSIDE the page (applied by the embed to its own DOM, never as OS input; the customer sees it and can stop it).
view | cobrowse
customerobjectrequired
Who the customer is, as the company knows them. At most 16 fields; names are 1 to 40 letters, digits, _, - or .; values are strings of at most 200 plain characters, numbers or booleans; at most 2 KB in all. Shown to the company's own agents and webhooks only, and never written to the audit trail (only the field names are).
customer_verifiedbooleanrequired
ownerstringrequired
originstring
created_atintegerrequired
expires_atintegerrequired
joined_atinteger
joined_bystring
ended_atinteger
end_reasonstring
{
  "id": "string",
  "type": "support.session.joined",
  "created": 0,
  "data": {
    "support_session": {
      "id": "string",
      "state": "waiting",
      "mode": "view",
      "customer": {},
      "customer_verified": true,
      "owner": "string",
      "origin": "string",
      "created_at": 0,
      "expires_at": 0,
      "joined_at": 0,
      "joined_by": "string",
      "ended_at": 0,
      "end_reason": "string"
    }
  }
}

Responses

200 Any 2xx acknowledges the delivery.
WEBHOOKsupport.session.ended

A support session ended (the customer stopped it, their tab went away, or it expired).

Parameters

GaiaDesk-Signaturestringheaderrequired
t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" keyed with the webhook secret>. Reject a delivery whose t is more than five minutes off, and de-duplicate by the event id.

Payload

application/json

support.session.joined / support.session.ended. id is stable across retries. Never carries the join code, the desk or the embed token.

idstringrequired
typestringrequired
support.session.joined | support.session.ended
createdintegerrequired
dataobjectrequired
Show child parameters
support_sessionobjectrequired
Show child parameters
idstringrequired
statestringrequired
waiting | joined | ended | expired
modestringrequired
view: the agent sees the shared tab. cobrowse: the agent may also point, highlight, click, scroll and type INSIDE the page (applied by the embed to its own DOM, never as OS input; the customer sees it and can stop it).
view | cobrowse
customerobjectrequired
Who the customer is, as the company knows them. At most 16 fields; names are 1 to 40 letters, digits, _, - or .; values are strings of at most 200 plain characters, numbers or booleans; at most 2 KB in all. Shown to the company's own agents and webhooks only, and never written to the audit trail (only the field names are).
customer_verifiedbooleanrequired
ownerstringrequired
originstring
created_atintegerrequired
expires_atintegerrequired
joined_atinteger
joined_bystring
ended_atinteger
end_reasonstring
{
  "id": "string",
  "type": "support.session.joined",
  "created": 0,
  "data": {
    "support_session": {
      "id": "string",
      "state": "waiting",
      "mode": "view",
      "customer": {},
      "customer_verified": true,
      "owner": "string",
      "origin": "string",
      "created_at": 0,
      "expires_at": 0,
      "joined_at": 0,
      "joined_by": "string",
      "ended_at": 0,
      "end_reason": "string"
    }
  }
}

Responses

200 Any 2xx acknowledges the delivery.
Updated