PT EN

Programadores: Sessões da CLI

URL base: $BUSINESS_API

Listar sessões da CLI

Registos

GET /developer/cli-sessions

Returns the tenant's live CLI sessions, newest first, with cursor pagination, so the dashboard can show who is listening and to which events. Secrets are never returned here. Requires developer:read.

Parâmetros

limitinteger · consulta · opcional

Maximum resources to return (default 20, maximum 100).

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Live sessions

Mostrar atributos
dataarray of DeveloperCliSession · opcional
Mostrar atributos filhos
idstring · obrigatório

Session identifier, starting with cls_.

tenant_idstring · obrigatório

Tenant the session listens to.

eventsarray of string · obrigatório

Event types the session receives; empty means every type.

created_bystring · obrigatório

User who opened the session; only they can poll or end it.

created_atstring (date-time) · obrigatório

When the session was opened.

expires_atstring (date-time) · obrigatório

When the session ends unless polled again.

secretstring · opcional

The whsec_ signing secret, present only in the response that opens the session.

has_moreboolean · opcional
next_cursorstring · opcional

Erros 401 · 403

Permissões developer:read · Funções: admin, owner

curl -X GET "$BUSINESS_API/developer/cli-sessions" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "dev_20UrPQc1lwaN5oeD7Q8xFo2l3KG",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "events": [
        "event"
      ],
      "created_by": "created by",
      "created_at": "2026-11-19T09:30:00Z",
      "expires_at": "2026-11-19T09:30:00Z",
      "secret": "secret"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Abrir uma sessão da CLI

Registos

POST /developer/cli-sessions

Opens a session for the CLI's webhooks listen command: a temporary endpoint that receives the tenant's new events, signed with its own whsec_ secret, returned once in this response. events limits the session to some event types; empty means every type. The session lives while the CLI polls it and expires about 90 seconds after the last poll. Requires developer:write.

Corpo application/json

eventsarray of string · opcional

Event types to receive; empty or absent means every type.

Devolve

201 Session, with its secret shown once

Mostrar atributos
idstring · obrigatório

Session identifier, starting with cls_.

tenant_idstring · obrigatório

Tenant the session listens to.

eventsarray of string · obrigatório

Event types the session receives; empty means every type.

created_bystring · obrigatório

User who opened the session; only they can poll or end it.

created_atstring (date-time) · obrigatório

When the session was opened.

expires_atstring (date-time) · obrigatório

When the session ends unless polled again.

secretstring · opcional

The whsec_ signing secret, present only in the response that opens the session.

Erros 400 · 401 · 403

Permissões developer:write · Funções: admin, owner

curl -X POST "$BUSINESS_API/developer/cli-sessions" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "events": [
    "event"
  ]
}'
Resposta 201
{
  "id": "dev_20UrPQc1lwaN5oeD7Q8xFo2l3KG",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "events": [
    "event"
  ],
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "expires_at": "2026-11-19T09:30:00Z",
  "secret": "secret"
}

Esperar pelos eventos de uma sessão da CLI

Registos

GET /developer/cli-sessions/{id}/events

Long-polls a CLI session: returns the events published since the previous poll, oldest first and at most 50, each with its genuine payload and the Standard Webhooks headers signed with the session secret. When none is ready the request is held for up to wait seconds. Each poll extends the session. Only the user who opened the session can poll it; an expired or unknown session returns 404. Requires developer:read.

Parâmetros

idstring · caminho · obrigatório

Identifier of the CLI session, as returned when it was opened.

waitinteger · consulta · opcional

Seconds to hold the request while no event is ready, from 0 (answer at once) to 25.

Devolve

200 Events since the previous poll

Mostrar atributos
dataarray of DeveloperCliSessionEvent · obrigatório

Events since the previous poll, oldest first.

Mostrar atributos filhos
idstring · obrigatório

Event identifier.

typestring · obrigatório

Event type, for example invoice.paid.

created_atstring (date-time) · obrigatório

When the event was published.

payloadobject · obrigatório

The event body exactly as webhook endpoints receive it.

webhook_idstring · obrigatório

Value for the webhook-id header.

webhook_timestampinteger (int64) · obrigatório

Value for the webhook-timestamp header (Unix seconds).

webhook_signaturestring · obrigatório

Value for the webhook-signature header (v1,<base64 HMAC-SHA256>).

expires_atstring (date-time) · obrigatório

When the session ends unless polled again.

Erros 400 · 401 · 403 · 404

Permissões developer:read · Funções: admin, owner

curl -X GET "$BUSINESS_API/developer/cli-sessions/{id}/events" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "dev_2v3q459KmXHCUJVGQHR8WdLsQNb",
      "type": "active",
      "created_at": "2026-11-19T09:30:00Z",
      "payload": {},
      "webhook_id": "whk_2Fhestrmgp5E6phyoldkw1BQmj3",
      "webhook_timestamp": 1,
      "webhook_signature": "webhook signature"
    }
  ],
  "expires_at": "2026-11-19T09:30:00Z"
}

Terminar uma sessão da CLI

Registos

DELETE /developer/cli-sessions/{id}

Ends a CLI session at once; the CLI calls this when it exits. Only the user who opened the session can end it. Requires developer:write.

Parâmetros

idstring · caminho · obrigatório

Identifier of the CLI session to end.

Devolve

204 Session ended

Erros 401 · 403 · 404

Permissões developer:write · Funções: admin, owner

curl -X DELETE "$BUSINESS_API/developer/cli-sessions/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 204

Session ended