Webhooks

Enfileira um evento `ping` para este endpoint

POST /webhook-endpoints/{endpoint}/ping

Escopo webhooks:manage
Limite escrita 60/min

Respostas

202 Entrega criada.

data object obrigatório

id integer obrigatório

webhook_endpoint_id integer obrigatório

event_id string obrigatório

evt_... — igual ao Cuidaro-Event-Id; não muda entre tentativas nem no reenvio.

event_type string obrigatório

status string obrigatório

pending aguardando tentativa; failed com nova tentativa em next_attempt_at; succeeded (terminal); exhausted sem mais tentativas (terminal).

Valores: pending failed succeeded exhausted

attempt integer obrigatório

response_status integer (anulável) obrigatório

response_body string (anulável) obrigatório

Até 2.000 caracteres da resposta do seu endpoint.

duration_ms integer (anulável) obrigatório

error string (anulável) obrigatório

next_attempt_at string (anulável) obrigatório

null em status terminal.

formato date-time

last_attempted_at string (anulável) obrigatório

formato date-time

delivered_at string (anulável) obrigatório

formato date-time

created_at string (anulável) obrigatório

formato date-time

payload object obrigatório

Corpo de todo envio de webhook (App\Services\Api\Webhooks\ApiWebhookEnvelope).

id string obrigatório

evt_ + ULID em minúsculas. Chave de deduplicação: igual ao cabeçalho Cuidaro-Event-Id.

api_version string obrigatório

Valores: 2026-10-26

schema_version string obrigatório

Valores: 1

type string obrigatório

Valores: ping fiscal_invoice.issued fiscal_invoice.cancelled fiscal_invoice.cancellation_rejected service_order.invoiced

created_at string obrigatório

UTC, sufixo Z.

formato date-time

data object obrigatório

Conteúdo específico do evento (ver webhooks).

404 Recurso inexistente, excluído ou de outra empresa/integração. Códigos possíveis: RESOURCE_NOT_FOUND.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

Catálogo estável de códigos de erro (App\Enums\ApiErrorCode). Código publicado nunca é renomeado nem removido; códigos novos podem surgir — trate valor desconhecido como erro genérico do status HTTP. O status, o título e o type de cada código estão em x-cuidaro-error-catalog.

Valores: AUTH_CREDENTIALS_INVALID AUTH_TOKEN_EXPIRED AUTH_TOKEN_MISSING AUTH_TOKEN_INVALID AUTH_SCOPE_INSUFFICIENT AUTH_TENANT_SUSPENDED AUTH_TENANT_PLAN_WITHOUT_API ACCESS_DENIED BAD_REQUEST VALIDATION_FAILED FIELD_REQUIRED FIELD_TYPE_INVALID FIELD_MAX_LENGTH FIELD_ENUM_INVALID FIELD_INVALID IDEMPOTENCY_KEY_MISSING IDEMPOTENCY_KEY_INVALID IDEMPOTENCY_KEY_CONFLICT IDEMPOTENCY_KEY_IN_PROGRESS RESOURCE_NOT_FOUND METHOD_NOT_ALLOWED RESOURCE_STATE_CONFLICT PLAN_QUOTA_EXCEEDED PAYLOAD_TOO_LARGE RATE_LIMIT_EXCEEDED HTTP_ERROR INTERNAL_ERROR SERVICE_UNAVAILABLE WEBHOOK_URL_NOT_ALLOWED RESOURCE_ALREADY_EXISTS SETTLEMENT_AMOUNT_MISMATCH EXTERNAL_SETTLEMENT_NOT_ALLOWED EXTERNAL_SETTLEMENT_ACCOUNT_MISSING

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

409 Endpoint desativado. Códigos possíveis: RESOURCE_STATE_CONFLICT.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

401 Token ausente, inválido, revogado ou expirado. Códigos: AUTH_TOKEN_MISSING, AUTH_TOKEN_INVALID, AUTH_TOKEN_EXPIRED.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

403 Escopo insuficiente ou empresa sem acesso à API. Códigos possíveis: AUTH_SCOPE_INSUFFICIENT, AUTH_TENANT_SUSPENDED, AUTH_TENANT_PLAN_WITHOUT_API, ACCESS_DENIED.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

413 Corpo acima de 512 KB. Códigos possíveis: PAYLOAD_TOO_LARGE.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

429 Limite de requisições excedido. Código: RATE_LIMIT_EXCEEDED.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

500 Erro interno, sem mensagem interna nem stack trace. Códigos possíveis: INTERNAL_ERROR.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

Requisição

cURL

curl -X POST 'https://cuidaro.com.br/api/v1/webhook-endpoints/7/ping' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $TOKEN"

PHP

// composer require guzzlehttp/guzzle
$client = new \GuzzleHttp\Client(['base_uri' => 'https://cuidaro.com.br/api/v1/']);
$token = getenv('CUIDARO_TOKEN');

$response = $client->request('POST', 'webhook-endpoints/7/ping', [
    'headers' => ['Accept' => 'application/json', 'Authorization' => 'Bearer '.$token],
    'http_errors' => false,
]);

$data = json_decode((string) $response->getBody(), true);

Node.js

const token = process.env.CUIDARO_TOKEN;

const response = await fetch('https://cuidaro.com.br/api/v1/webhook-endpoints/7/ping', {
  method: 'POST',
  headers: { 'Accept': 'application/json', Authorization: `Bearer ${token}` },
});
const data = response.status === 204 ? null : await response.json();

Python

import os

import requests

token = os.environ["CUIDARO_TOKEN"]

response = requests.request(
    "POST",
    "https://cuidaro.com.br/api/v1/webhook-endpoints/7/ping",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    timeout=15,
)
data = response.json() if response.status_code != 204 else None

Resposta 202

{
  "data": {
    "id": 731,
    "webhook_endpoint_id": 42,
    "event_id": "texto",
    "event_type": "texto",
    "status": "pending",
    "attempt": 1,
    "response_status": 1,
    "response_body": "texto",
    "duration_ms": 1,
    "error": "texto",
    "next_attempt_at": "2026-10-27T11:00:00-03:00",
    "last_attempted_at": "2026-10-27T11:00:00-03:00",
    "delivered_at": "2026-10-27T11:00:00-03:00",
    "created_at": "2026-10-27T11:00:00-03:00",
    "payload": {
      "id": "texto",
      "api_version": "2026-10-26",
      "schema_version": "1",
      "type": "ping",
      "created_at": "2026-10-27T11:00:00-03:00",
      "data": {}
    }
  }
}

Erro 409 (exemplo)

{
  "type": "https://cuidaro.com.br/errors/resource-state-conflict",
  "title": "Resource State Conflict",
  "status": 409,
  "detail": "Operação inválida para o estado atual do recurso.",
  "instance": "/api/v1/webhook-endpoints/7/ping",
  "code": "RESOURCE_STATE_CONFLICT"
}