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 correctednotes_removeDiagnose: a diagnosis is removed from a noteaddDiagnosis: 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
2xxstatus 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.