Webhooks

Get a request to your endpoint when something changes in Kaddio, so your systems stay in sync without polling.

In the examples, replace values in capitals, such as YOUR_ORG and YOUR_API_TOKEN, with your own.

Kaddio has two kinds of webhooks:

  • Collection hooks fire when a document is created, changed or removed, filtered by a query you choose.
  • Method hooks fire when a specific clinical action happens, such as correcting a note.

Both are managed with the GraphQL API by a user with API admin access.

Collection hooks #

Hooks follow changes to data rather than named events. To be told when a journal contact is signed, you do not listen for a "sign" event. You add an UPDATE hook on contacts with the query { isSigned: { EQ: true } }. The query uses the same filters as the find queries, which makes almost any hook possible.

Data Create a hook Remove a hook List hooks
Journal contacts insertContactHook removeContactHook findContactHooks
Users and clients insertUserHook removeUserHook findUserHooks
Bookings insertEventHook removeEventHook findEventHooks
Invoices insertInvoiceHook removeInvoiceHook findInvoiceHooks
Messages insertMessageHook removeMessageHook findMessageHooks
Form answers insertFormAnswerHook removeFormAnswerHook findFormAnswerHooks
Cases insertCaseHook removeCaseHook findCaseHooks

The type decides when the hook fires:

  • INSERT: when a new document matches the query.
  • UPDATE: when the changed fields match the query.
  • REMOVE: when a removed document matches the query.
mutation {
    insertContactHook(
        type: UPDATE
        query: { isSigned: { EQ: true } }
        callbackUrl: "https://example.com/webhooks/kaddio"
        webhookSecret: "A_LONG_RANDOM_SECRET"
    )
}

Kaddio sends a POST to your callbackUrl with the full document as JSON in the body. For the signed-contact hook above, it looks like this, shortened:

{
    "_id": "F8vC8R3egRDv7XDzX",
    "orgId": "Og3hJ6kL9mP2qR5sT",
    "clientId": "NTFeo9LR2vkdf8WHL",
    "hostId": "Xb7kQ2mN9pR4sT6vW",
    "contactTypeId": "Pq4rS7tU0vW3xY6zA",
    "typeName": "Follow-up",
    "date": "2026-07-08T09:00:00.000Z",
    "created": "2026-07-08T08:55:12.000Z",
    "isSigned": true,
    "signedAt": "2026-07-08T09:40:03.000Z",
    "signedBy": "Xb7kQ2mN9pR4sT6vW"
}

The body is the document as Kaddio stores it, so field names can differ from the GraphQL API and more fields can be present. Dates are ISO 8601 strings. Use the _id to fetch what you need through the GraphQL API.

Not every change in Kaddio triggers a hook, so use hooks to stay up to date rather than as the only way to get a complete copy of your data.

Method hooks #

Method hooks fire when one of these actions is performed, whatever data it changes:

  • correctNote: a signed note is corrected
  • notes_removeDiagnose: a diagnosis is removed from a note
  • addDiagnosis: a diagnosis is added
mutation {
    createMethodHook(
        methodName: addDiagnosis
        callbackUrl: "https://example.com/webhooks/kaddio"
        webhookSecret: "A_LONG_RANDOM_SECRET"
    )
}

List them with findMethodHooks and remove one with deleteMethodHook(id: "HOOK_ID").

Kaddio sends a POST with this body, where actorId is the user who performed the action:

{
    "actorId": "USER_ID",
    "arguments": []
}

Verifying requests #

When a hook has a webhookSecret, every request is signed with these headers:

Header Content
Kaddio-Id A unique ID for the event, such as evt_3f1c…
Kaddio-Timestamp When the event was sent, in Unix seconds
Kaddio-Signature v1= followed by a Base64 HMAC-SHA256 signature

The signature is computed with your secret over the Kaddio-Id header, a dot, the Kaddio-Timestamp header, a dot and the raw request body. Compute it yourself and compare:

import crypto from 'node:crypto';

// rawBody is the request body as a string, before JSON parsing
function isFromKaddio(headers, rawBody, secret) {
    const payload = `${headers['kaddio-id']}.${headers['kaddio-timestamp']}.${rawBody}`;
    const expected = 'v1=' + crypto.createHmac('sha256', secret).update(payload).digest('base64');
    const received = headers['kaddio-signature'] ?? '';

    return (
        expected.length === received.length &&
        crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))
    );
}

To protect against replayed requests, also reject requests whose timestamp is more than a few minutes old.

Good practice #

  • Respond with a 2xx status quickly, and do slow work after responding.
  • Each event is sent once, so monitor your endpoint and log what you receive.
  • Use a different secret for each hook.

Questions? Ask the help assistant here on the site, or ask Kaddio AI inside Kaddio. You can also contact support.