Webhooks: get notified when data changes

Instead of repeatedly asking the API "anything new?", subscribe to events once and Roldesk will send them to your server the moment they happen.

Add an endpoint

In Settings → Developer → Webhooks, add the URL that should receive events and tick the events you care about (for example work_order.completed or invoice.created). We show a signing secret once — store it securely. You can also test, disable, or delete an endpoint at any time.

What you receive

Each delivery is a small JSON POST with headers:

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

The body is a thin event — use the id to fetch the full object from the REST API:

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

Verify the signature

Always confirm a delivery is genuinely from Roldesk before acting on it (Node example):

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));
}

Reliability

Failed deliveries retry automatically with backoff (up to 6 attempts). An endpoint that keeps failing is disabled so nothing piles up. Events fire on every change — from the web app, the mobile app, the API, or automatic actions like contract renewals.