Webhooks

Histórico de entregas do endpoint (paginado, mais recentes primeiro)

GET /webhook-endpoints/{endpoint}/deliveries

Escopo webhooks:manage
Limite leitura 120/min

Parâmetros

page integer · query

de 1 a ∞

per_page integer · query

de 1 a 100

status string · query

Valores: pending failed succeeded exhausted

Respostas

200 Página do histórico.

data array de 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).

meta object obrigatório

current_page integer obrigatório

per_page integer obrigatório

total integer obrigatório

last_page integer obrigatório

links object obrigatório

first string obrigatório

formato uri

last string obrigatório

formato uri

prev string (anulável) obrigatório

formato uri

next string (anulável) obrigatório

formato uri

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.

422 Dados inválidos — detalhes em errors/error_codes.

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.

errors object

Mensagens por campo (pt-BR).

error_codes object

Códigos estáveis por campo: FIELD_REQUIRED, FIELD_TYPE_INVALID, FIELD_MAX_LENGTH, FIELD_ENUM_INVALID, FIELD_INVALID, WEBHOOK_URL_NOT_ALLOWED.

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 GET 'https://cuidaro.com.br/api/v1/webhook-endpoints/7/deliveries' \
  -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('GET', 'webhook-endpoints/7/deliveries', [
    '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/deliveries', {
  method: 'GET',
  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(
    "GET",
    "https://cuidaro.com.br/api/v1/webhook-endpoints/7/deliveries",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    timeout=15,
)
data = response.json() if response.status_code != 204 else None

Resposta 200

{
  "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": {}
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 1,
    "total": 1,
    "last_page": 1
  },
  "links": {
    "first": "https://cuidaro.com.br/…",
    "last": "https://cuidaro.com.br/…",
    "prev": "https://cuidaro.com.br/…",
    "next": "https://cuidaro.com.br/…"
  }
}

Erro 422 (exemplo)

{
  "type": "https://cuidaro.com.br/errors/validation-failed",
  "title": "Validation Failed",
  "status": 422,
  "detail": "Os dados enviados são inválidos.",
  "instance": "/api/v1/webhook-endpoints/7/deliveries",
  "code": "VALIDATION_FAILED"
}