webhooks

Embed
Preview of the card
<a href="https://forumulate.com/p/gaiadesk/docs/ref-webhooks"><img src="https://forumulate.com/api/public/orgs/gaiadesk/spaces/docs/pages/bc5b5449-b4c7-420a-bdd2-b311d2596bd4/social-card.svg?v=3e7ae33eec8b" alt="webhooks" width="600" height="315"></a>
GEThttps://api.gaiadesk.net/v1/webhooksScope webhooks

The account's webhook subscriptions (never their secrets).

Code samples

cURL
curl -X GET "https://api.gaiadesk.net/v1/webhooks" \
  -H "Authorization: Bearer $GAIADESK_API_KEY"
TypeScript
Python
Go
PHP
Ruby
Java

Responses

200 The subscriptions.
Example
{
  "webhooks": [
    {
      "id": "string",
      "url": "string",
      "events": [
        "desk.online"
      ],
      "description": "string",
      "created_at": 0
    }
  ]
}
Schema
webhooksApiWebhook[]required
Show child parameters
idstringrequired
urlstringrequired
eventsApiWebhookEventType[]required
descriptionstringrequired
created_atintegerrequired
Headers
X-Request-Idstring
This request's id (req_…), also in every error body. Quote it to support.
401 No credential, or one that does not verify (refused, unauthenticated).
Example
{
  "error": {
    "desk": "string",
    "kind": "string",
    "message": "string",
    "reason": "string",
    "request_id": "string",
    "status": 0
  },
  "e2e": {
    "v": 0,
    "events": [
      {
        "seq": 0,
        "nonce": "string",
        "ciphertext": "string"
      }
    ]
  }
}
Schema
errorError & objectrequired
The CLI's error object plus this request's id.
Show child parameters
deskstring
The desk it concerned, when there was one.
kindstringrequired
The six kinds a program branches on. Stable: a new kind would be a breaking change, so match with a wildcard arm anyway.
messagestringrequired
reasonstring
The finer cause: offline, unknown_desk, not_online, network, not_signed_in, timeout, local, …
request_idstringrequired
statusinteger
Only in a held body (GaiaDesk-Held) — the HTTP status this failure would have had, had its 200 not been sent already.
e2eobject
An end-to-end encrypted operation's events; the last opens to the desk's real error (its message here is a placeholder).
Show child parameters
vintegerrequired
eventsApiE2eFrame[]required
Show child parameters
seqintegerrequired
noncestringrequired
ciphertextstringrequired
403 The credential lacks the scope, or may not use this API (refused).

Same as 401 · GET /webhooks

429 Over this key's rate limit (refused, rate_limited).

Same as 401 · GET /webhooks

Headers
Retry-Afterinteger
Seconds to wait before trying again.
RateLimit-Limitinteger
Requests allowed per window for this key.
RateLimit-Remaininginteger
Requests left in the current window.
RateLimit-Resetinteger
Seconds until the window resets.
POSThttps://api.gaiadesk.net/v1/webhooksScope webhooks

Subscribe an HTTPS endpoint to events. The signing secret is returned once.

Parameters

Idempotency-Keystringheader
Up to 255 printable ASCII characters. A retry with the same key and the same request within 24 hours gets the first answer again (Idempotent-Replayed: true); the same key with a different request is refused (usage, idempotency_key_reused).

Request body

application/json
urlstringrequired
An https:// URL on the public internet (no private, loopback or link-local address).
eventsApiWebhookEventType[]required
descriptionstring
{
  "url": "string",
  "events": [
    "desk.online"
  ],
  "description": "string"
}

Code samples

cURL
curl -X POST "https://api.gaiadesk.net/v1/webhooks" \
  -H "Authorization: Bearer $GAIADESK_API_KEY" \
  -H "Idempotency-Key: <value>" \
  -H "Content-Type: application/json" \
  -d '{"url":"string","events":["desk.online"],"description":"string"}'
TypeScript
Python
Go
PHP
Ruby
Java

Responses

201 Subscribed. Keep secret; it is never shown again.
Example
{
  "id": "string",
  "url": "string",
  "events": [
    "desk.online"
  ],
  "description": "string",
  "created_at": 0,
  "secret": "string"
}
Schema
idstringrequired
urlstringrequired
eventsApiWebhookEventType[]required
descriptionstringrequired
created_atintegerrequired
secretstringrequired
The signing secret (whsec_…). Shown once.
Headers
X-Request-Idstring
This request's id (req_…), also in every error body. Quote it to support.
Idempotent-Replayedstring
true when this answer is a stored one, replayed for a repeated Idempotency-Key.
400 The request is malformed (usage).

Same as 401 · GET /webhooks

401 No credential, or one that does not verify (refused, unauthenticated).

Same as 401 · GET /webhooks

403 The credential lacks the scope, or may not use this API (refused).

Same as 401 · GET /webhooks

429 Over this key's rate limit (refused, rate_limited).

Same as 401 · GET /webhooks

Headers
Retry-Afterinteger
Seconds to wait before trying again.
RateLimit-Limitinteger
Requests allowed per window for this key.
RateLimit-Remaininginteger
Requests left in the current window.
RateLimit-Resetinteger
Seconds until the window resets.
DELETEhttps://api.gaiadesk.net/v1/webhooks/{webhook_id}Scope webhooks

Unsubscribe. Deliveries still queued for it are dropped.

Parameters

webhook_idstringpathrequired

Code samples

cURL
curl -X DELETE "https://api.gaiadesk.net/v1/webhooks/{webhook_id}" \
  -H "Authorization: Bearer $GAIADESK_API_KEY"
TypeScript
Python
Go
PHP
Ruby
Java

Responses

200 Deleted.
Example
{
  "deleted": "string"
}
Schema
deletedstringrequired
Headers
X-Request-Idstring
This request's id (req_…), also in every error body. Quote it to support.
401 No credential, or one that does not verify (refused, unauthenticated).

Same as 401 · GET /webhooks

403 The credential lacks the scope, or may not use this API (refused).

Same as 401 · GET /webhooks

404 No such desk or resource visible to the caller (unreachable, unknown_desk).

Same as 401 · GET /webhooks

429 Over this key's rate limit (refused, rate_limited).

Same as 401 · GET /webhooks

Headers
Retry-Afterinteger
Seconds to wait before trying again.
RateLimit-Limitinteger
Requests allowed per window for this key.
RateLimit-Remaininginteger
Requests left in the current window.
RateLimit-Resetinteger
Seconds until the window resets.
Updated