API de Webhooks

Notificações de eventos (cobrança/pagamento) com retry e log

12 endpoints · base https://api.comando.one/v1 · autenticação por chave cmd_live_…

GET/webhooks

Listar webhooks da empresa

Lista todos os webhooks da empresa. Webhooks são por empresa (não por API key) e você pode ter vários, cada um com seus eventos.

webhooks:manage

Parâmetros, corpo, resposta e exemplo

Resposta 200 — Lista

`id`	string (uuid)
`name`	string \| null	Rótulo opcional do webhook
`url`	string (uri)
`events`	array de string
`active`	boolean
`created_at`	string (date-time)
`updated_at`	string (date-time)

Exemplo

curl -X GET "https://api.comando.one/v1/webhooks" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

POST/webhooks

Criar webhook

Cria um webhook. O `secret` vem no corpo do 201 e **só nessa vez** — guarde-o. É com ele que você confere a assinatura de cada entrega. Headers de toda entrega: - `x-signature` — HMAC-SHA256 do **corpo cru** (os bytes recebidos, antes de qualquer parse/reserialização), em hexadecimal minúsculo. Compare em tempo constante e rejeite o que não bater: é o que distingue uma entrega nossa de qualquer POST na sua URL. - `x-event` — o evento (ex.: `invoice.paid`). - `x-delivery-id` — id da entrega; serve para você deduplicar retentativas (há até 3 tentativas, com backoff de 30s e 2min).

webhooks:manage

Parâmetros, corpo, resposta e exemplo

Corpo (JSON)

`name`	string \| null	Rótulo opcional. No PUT /webhooks/payments, omitido preserva o rótulo atual; null apaga.
`url`obrigatório	string (uri)	Deve começar com https://
`events`	array de string	Eventos assinados (default: charge.paid, charge.cancelled, charge.expired)
`active`	boolean

Resposta 201 — Webhook criado (inclui secret único)

`webhook`	object
`secret`	string	Segredo HMAC-SHA256. Devolvido SÓ nesta resposta; assina o header x-signature de cada entrega.
`secret_note`	string

Exemplo

curl -X POST "https://api.comando.one/v1/webhooks" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"url":"<string (uri)>"}'

DELETE/webhooks/{id}

Excluir webhook

webhooks:manage

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Resposta 204 — Excluído

Sem corpo.

Exemplo

curl -X DELETE "https://api.comando.one/v1/webhooks/{id}" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

GET/webhooks/{id}

Obter webhook

webhooks:manage

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Resposta 200 — Webhook

`id`	string (uuid)
`name`	string \| null	Rótulo opcional do webhook
`url`	string (uri)
`events`	array de string
`active`	boolean
`created_at`	string (date-time)
`updated_at`	string (date-time)

Exemplo

curl -X GET "https://api.comando.one/v1/webhooks/{id}" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

PATCH/webhooks/{id}

Atualizar webhook

webhooks:manage

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Corpo (JSON)

`name`	string \| null	Rótulo opcional. No PUT /webhooks/payments, omitido preserva o rótulo atual; null apaga.
`url`obrigatório	string (uri)	Deve começar com https://
`events`	array de string	Eventos assinados (default: charge.paid, charge.cancelled, charge.expired)
`active`	boolean

Resposta 200 — Atualizado

`id`	string (uuid)
`name`	string \| null	Rótulo opcional do webhook
`url`	string (uri)
`events`	array de string
`active`	boolean
`created_at`	string (date-time)
`updated_at`	string (date-time)

Exemplo

curl -X PATCH "https://api.comando.one/v1/webhooks/{id}" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"url":"<string (uri)>"}'

POST/webhooks/{id}/test

Enviar evento de teste

Enfileira um evento `webhook.test` direcionado apenas a este webhook (para validar a URL e a verificação de assinatura).

webhooks:manage

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Resposta 202 — Teste enfileirado

`message`	string
`delivery`	object

Exemplo

curl -X POST "https://api.comando.one/v1/webhooks/{id}/test" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

GET/webhooks/deliveries

Listar entregas de webhook (log)

Histórico de entregas com status, tentativas e erro. Entregas são reprocessadas automaticamente com backoff.

webhooks:manage

Parâmetros, corpo, resposta e exemplo

Parâmetros

`page`(query)	integer	Número da página (default: 1)
`per_page`(query)	integer	Itens por página (default: 20, máx: 100)
`status`(query)	"pending" \| "delivering" \| "delivered" \| "failed"
`event`(query)	string

Resposta 200 — Listagem paginada

`id`	string (uuid)
`webhook_id`	string (uuid)
`event`	string
`status`	"pending" \| "delivering" \| "delivered" \| "failed"
`attempts`	integer
`max_attempts`	integer
`http_status`	integer \| null
`last_error`	string \| null
`next_retry_at`	string \| null (date-time)
`delivered_at`	string \| null (date-time)
`created_at`	string (date-time)
`updated_at`	string (date-time)

Exemplo

curl -X GET "https://api.comando.one/v1/webhooks/deliveries" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

POST/webhooks/deliveries/{id}/redeliver

Reenviar entrega

webhooks:manage

Parâmetros, corpo, resposta e exemplo

Parâmetros

idobrigatório(path) string (uuid)

Resposta 200 — Re-enfileirada

`id`	string (uuid)
`webhook_id`	string (uuid)
`event`	string
`status`	"pending" \| "delivering" \| "delivered" \| "failed"
`attempts`	integer
`max_attempts`	integer
`http_status`	integer \| null
`last_error`	string \| null
`next_retry_at`	string \| null (date-time)
`delivered_at`	string \| null (date-time)
`created_at`	string (date-time)
`updated_at`	string (date-time)

Exemplo

curl -X POST "https://api.comando.one/v1/webhooks/deliveries/{id}/redeliver" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

GET/webhooks/events

Catálogo de eventos disponíveis

Lista todos os eventos que um webhook pode assinar (key, label, group).

webhooks:manage

Parâmetros, corpo, resposta e exemplo

Resposta 200 — Catálogo

`key`	string
`label`	string
`group`	string

Exemplo

curl -X GET "https://api.comando.one/v1/webhooks/events" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

DELETE/webhooks/payments

Remover a configuração de webhook de pagamentos

webhooks:manage

Parâmetros, corpo, resposta e exemplo

Resposta 200 — Removido

Sem corpo.

Exemplo

curl -X DELETE "https://api.comando.one/v1/webhooks/payments" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

GET/webhooks/payments

Obter configuração de webhook

webhooks:manage

Parâmetros, corpo, resposta e exemplo

Resposta 200 — Configuração atual

webhook object ou null

Exemplo

curl -X GET "https://api.comando.one/v1/webhooks/payments" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

PUT/webhooks/payments

Registrar/atualizar webhook

Cria ou atualiza a URL de callback. O `secret` é retornado apenas na criação — guarde-o. Cada entrega vai assinada no header `x-signature` = HMAC-SHA256 do corpo cru, em hexadecimal minúsculo, junto de `x-event` e `x-delivery-id`.

webhooks:manage

Parâmetros, corpo, resposta e exemplo

Corpo (JSON)

`name`	string \| null	Rótulo opcional. No PUT /webhooks/payments, omitido preserva o rótulo atual; null apaga.
`url`obrigatório	string (uri)	Deve começar com https://
`events`	array de string	Eventos assinados (default: charge.paid, charge.cancelled, charge.expired)
`active`	boolean

Resposta 200 — Webhook atualizado

webhook object

Exemplo

curl -X PUT "https://api.comando.one/v1/webhooks/payments" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"url":"<string (uri)>"}'

Início rápido, autenticação, SDK, servidor MCP e o playground para testar sem escrever código estão na documentação completa. A especificação em OpenAPI está em api.comando.one/openapi.json.

Outros recursos da API

Clientes (16)Contratos (13)Faturas (12)Serviços (9)Split de Pagamentos (9)Catálogos (7)Propostas (6)NFS-e (6)

Ou deixe a IA usar a API por você

O servidor MCP expõe estes mesmos recursos ao ChatGPT, Claude ou Gemini — com OAuth, sem chave de API.

Conectar um assistente