Webhooks
Receber webhooks
Cadastre um endereço HTTPS com POST /webhook-endpoints e o Cuidaro avisa quando a OS é faturada e quando a nota é autorizada, cancelada ou tem o cancelamento recusado.
- O segredo
whsec_...aparece só na criação e na troca de segredo. - URL só
https://, resolvendo para IP público, sem redirecionamento. - Os avisos de negócio valem só para OS criadas pela API e vão só para a integração que criou a OS.
- Teste com
ping.
Formato do envio
| Cabeçalho | Conteúdo |
|---|---|
Cuidaro-Signature | t=<unix>,v1=<hex> |
Cuidaro-Event-Id | id do evento (evt_…); não muda entre tentativas |
Cuidaro-Event-Type | tipo do evento |
Envelope: id, api_version, schema_version, type, created_at e data. Cada evento tem página própria no menu, com os campos de data e um exemplo.
Responder e deduplicar
- Responda 2xx em até 10 s. Grave o evento, responda e processe depois.
- Guarde o
Cuidaro-Event-Idprocessado e ignore repetidos. - A ordem não é garantida: decida pelo estado do recurso.
Retentativas
Sem 2xx, o Cuidaro tenta de novo após 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h e 24 h: 9 tentativas em cerca de 2,9 dias. Esgotadas, a entrega pode ser reenviada com redeliver.
GET /service-orders/{id}.O que a empresa vê
O dono ou administrador da empresa acompanha seus endpoints em Configurações → Integrações (API) → Webhooks: histórico de entregas, reenvio, desativar/reativar e remover (que apaga o histórico). A tela não cadastra endpoint nem mostra ou troca o segredo — isso é só seu, pela API. Se um endpoint parar de receber, confira se a empresa não o desativou (is_active).
data, uma vez só, para mudanças das últimas 72 h). Como rede extra, consulte periodicamente as OS que ainda esperam algo com GET /service-orders/{id} — é o único caminho para a NFS-e recusada na emissão, que não gera evento.Próximo: verificar a assinatura.
Referência gerada a partir do contrato OpenAPI 3.1 da API v1 (versão 2026-10-26), conferido contra o código por teste automatizado. Dúvidas: suporte@cuidaro.com.br.