Voor ontwikkelaars

Webhooks & API

Koppel MyCompanyDesk aan je eigen systemen. Ontvang realtime events met webhooks en beheer programmatische toegang met API-sleutels. Beschikbaar op het Office-abonnement.

API-sleutels

API-sleutels geven programmatische toegang tot je account. Je maakt en beheert ze in de app onder Instellingen → API-sleutels. De sleutel wordt eenmalig getoond, daarna alleen het voorvoegsel.

Scopes: read, write of admin, per sleutel in te stellen.
IP-allowlist: beperk een sleutel tot specifieke IP-adressen.
Vervaldatum: laat een sleutel automatisch verlopen.
Intrekken: zet een sleutel direct stop wanneer je wilt.

Stuur de sleutel mee in de X-API-Key-header. De basis-URL is:

https://api.mycompanydesk.com

Bewaar je sleutel veilig en deel 'm nooit in clientcode of een openbare repository. Ingetrokken of verlopen sleutels werken direct niet meer.

Webhooks

Met webhooks ontvang je een melding zodra er iets gebeurt in je account, bijvoorbeeld wanneer een factuur betaald wordt. Je maakt een abonnement aan onder Instellingen → Webhooks: geef een naam en een URL op en kies de events waarop je wilt luisteren (of laat de lijst leeg om op alles te luisteren).

Bij elk event stuurt MyCompanyDesk een POST met Content-Type: application/json naar jouw URL, met deze headers:

Header	Inhoud
`X-MCD-Event-Type`	Het type event, bijvoorbeeld `invoice.paid`.
`X-MCD-Event-Id`	Uniek id van het event.
`X-MCD-Delivery-Id`	Uniek id van deze leveringspoging.
`X-MCD-Signature`	HMAC-SHA256 van de ruwe body, als hex.

Handtekening verifiëren

Verifieer elke webhook met het secret dat je bij het aanmaken van het abonnement kreeg. Bereken de HMAC-SHA256 over de ruwe (onbewerkte) body en vergelijk die met de X-MCD-Signature-header:

const crypto = require("crypto");

function verifySignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Gebruik de ruwe request-body voor de berekening, niet de opnieuw geserialiseerde JSON. Een test stuur je vanuit de app met het event test.ping.

Beschikbare events

Event	Wanneer
`test.ping`	Handmatige testlevering vanuit de app.
`invoice.created`	Een factuur is aangemaakt.
`invoice.updated`	Een factuur is gewijzigd.
`invoice.paid`	Een factuur is betaald.
`invoice.overdue`	Een factuur is over de vervaldatum.
`expense.created`	Een uitgave is toegevoegd.
`expense.updated`	Een uitgave is gewijzigd.
`expense.deleted`	Een uitgave is verwijderd.
`customer.created`	Een klant is toegevoegd.
`customer.updated`	Een klant is gewijzigd.
`inbox.thread.received`	Een nieuw gesprek is binnengekomen in je inbox.
`inbox.message.received`	Een nieuw bericht is binnengekomen in je inbox.

Elke levering wordt gelogd, zodat je in de app kunt zien welke webhooks zijn verstuurd en of ze aankwamen.

Vragen over een koppeling? Neem contact op, je praat rechtstreeks met de mensen die het bouwen.