Webhooks: seja avisado quando os dados mudam

Em vez de perguntar à API repetidamente "tem algo novo?", assine os eventos uma vez e o Roldesk os enviará ao seu servidor no momento em que acontecerem.

Adicione um endpoint

Em Configurações → Desenvolvedor → Webhooks, adicione a URL que deve receber os eventos e marque os eventos que lhe interessam (por exemplo work_order.completed ou invoice.created). Mostramos um segredo de assinatura uma única vez — guarde-o com segurança. Você também pode testar, desativar ou excluir um endpoint a qualquer momento.

O que você recebe

Cada entrega é um pequeno POST em JSON com cabeçalhos:

Roldesk-Event:      contract.renewed
Roldesk-Delivery:   <id da entrega>
Roldesk-Signature:  t=<unix_ts>,v1=<hmac-sha256 em hex>

O corpo é um evento enxuto — use o id para buscar o objeto completo na API REST:

{ "id": "…", "type": "contract.renewed", "created": "…",
  "data": { "object": "contract", "id": "…" } }

Verifique a assinatura

Sempre confirme que uma entrega é genuinamente do Roldesk antes de agir sobre ela (exemplo em Node):

import crypto from "crypto";
function verify(rawBody, header, secret) {
  const p = Object.fromEntries(header.split(",").map(x => x.split("=")));
  const expected = crypto.createHmac("sha256", secret)
    .update(`${p.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(p.v1), Buffer.from(expected));
}

Confiabilidade

Entregas com falha são repetidas automaticamente com espera progressiva (até 6 tentativas). Um endpoint que continua falhando é desativado para que nada se acumule. Os eventos disparam em cada mudança — pelo app web, pelo app mobile, pela API ou por ações automáticas como renovações de contratos.