API integration and webhooks explained: what they are and what to ask before anything is connected

What is an API integration?

An API integration lets two programs exchange data directly, without anyone retyping anything or sending a file. API stands for application programming interface: an agreed entrance through which another program retrieves or changes data, according to fixed rules and usually with a key.

In a service company, it is usually about a few fixed flows. The accounting software retrieves the posted invoices. Another program reads the customers or the installations. An automation tool creates a task as soon as an intervention is finished.

API or webhook: asking or being told

The difference lies in who takes the initiative.

• With an API, the other program asks. “Are there any new invoices since yesterday?” It asks at its own pace, for example every hour or at night, and with the right permissions it can also change data.
• With a webhook, your software reports it itself. As soon as something happens, such as an invoice being posted, a short message goes out to an internet address of the other program. So that program must always be reachable.

The two often work together. The webhook reports “invoice posted”, and the other program then retrieves the details of that invoice through the API.

An API key is an access, with permissions

An API key works like a password for a program. Whoever has the key gets the access attached to it, without being asked who they are. That is why three rules apply:

1. Give only what is needed. If accounting only reads invoices, the key only gets the permission to read invoices. A leaked key or a mistake in the integration can then never do more damage than what that key is allowed to do.
2. Let the integration run under its own user. Then you see what the integration does, and you can stop it without blocking a colleague.
3. Store the key like a password, and give it an end date. Never send it in an ordinary email. An expiry date forces a deliberate renewal. If the collaboration ends, revoke the key.

Why a webhook is signed

A webhook arrives at an address that can be reached from the internet. Anyone who knows that address could in principle send a fake message to it too, for example “invoice paid”. A signature solves that. Using a secret that only the two programs know, the sender calculates a code over the message and sends it along. The receiver recalculates the same code. If it matches, the message comes from the right sender and was not changed on the way. A common method is called HMAC-SHA256.

The signature only helps if the receiver actually checks it. So ask whoever builds the integration about it.

Ten questions before an API integration is built

An integration is a small project. Have the answers to these questions put in writing before anything is built:

1. Which data goes through it? Only posted invoices and credit notes, or customers and payments too?
2. In which direction? From your service software to accounting, the other way round, or both? And which program has the final say if an address differs between the two?
3. How often, or at what moment? Immediately via a webhook, or once a night via the API?
4. Who builds the integration? Your supplier, the supplier of the other program, or a third party? With what documentation?
5. Who maintains it? Programs change. Who adapts the integration, and who pays for that?
6. What happens when there is an error? Who is notified, where do you see what did not come through, and is it retried?
7. Who owns the key? Under which user does the integration run, and who keeps the key?
8. What permissions does the key get? Read only, or also change? And in which parts?
9. How do you withdraw the access? At the end of the collaboration, or if you suspect a leak.
10. How do you test? First with a few records, and who checks the result before everything goes live?

If personal data of your customers goes to another supplier, discuss with your legal adviser what you need to agree with that supplier. The questions to ask about where your data is stored are in data in the cloud.

Sometimes a file is enough

Not every exchange needs an integration. An export and an import do the same work, by hand:

If it is a monthly flow with few lines, or if the other program cannot use an API, a file is often the simplest route. If it becomes a daily task that someone has to remember every time, an integration is more likely to be worth the effort.

An example: invoices to accounting

A water treatment company posts its invoices in its service software. The accountant works in their own package and receives an export by email every month. They suggest doing this through an API integration.

The office manager asks the ten questions. The answer: only posted invoices and credit notes, in one direction, once a night. The supplier of the accounting package builds the integration. The key runs under a separate user who may only read invoices, and expires after one year, so that someone renews it deliberately. When there is an error, the office manager gets a message from the accounting package. During the first month the export keeps running alongside, and the accountant compares the two. After that, the export is dropped.

How it works in Digitalnatie Service Suite

In Digitalnatie Service Suite, the connection with other software is set up in the configuration, on the integrations screen, in the tab for the API and webhooks. At the top of the tab are the address of the API and a link to its documentation, for whoever builds the integration.

• A permission on request: API keys and webhooks require a technical permission that no role template gives, not even the administrator’s. You ask Digitalnatie for it.
• A separate user: when you create an API key, you give it a name and choose the user whose permissions it takes over exactly. Preferably choose a separate user with limited permissions. The administrator invites that user and gives them their roles in the role management.
• Only the access needed: you tick what the software may read (customers, sites, installations, interventions, contracts, stock, invoices, reports) and what it may change. If you wish, you set an expiry date and restrict the key to certain IP addresses.
• Shown once: Service Suite keeps only a fingerprint of the key. Copy it straight away and store it like a password. You can replace it with a new key, or revoke it permanently.
• Webhooks: you give a name and a receiving address, an https address on the internet. Internal addresses are refused. You choose which events are reported, for example an intervention created, an intervention finished, or an invoice or credit note posted.
• Signed and resent: every notification is signed with HMAC-SHA256, so that the receiver can check that it comes from Service Suite. If a delivery fails, it is retried, at increasingly longer intervals. After 20 failures in a row, the webhook is disabled, and you enable it again once the problem has been solved.
• Without an integration: the administrator imports data from an Excel or CSV template, checked first. The list of interventions and the reports can be exported as CSV; the financial overview has an Excel export of the profit and loss account, for those allowed to open it.

Good to know: whether an accounting package or other software can connect this way depends on what that software supports. Ask its supplier. Deleting a webhook also deletes the history of its deliveries. In the services tab you can, among other things, connect and test WhatsApp Business and MCP servers, but nothing is sent through those connections yet.

Who may do what in the software itself is explained in user roles and permissions, and how to load a customer file in importing customer data. See also the invoicing and purchasing module.

Frequently asked questions

What is the difference between an API and a webhook?

With an API, another program retrieves data itself, at its own pace, and with the right permissions it can also change data. With a webhook, your software itself reports that something has happened, such as a posted invoice, by sending a message to an internet address of the other program. The two often work together.

What is an API key?

An API key is an access for a program, like a password for a person. Whoever has the key gets the permissions attached to it. So give a key only the permissions the integration needs, and store it like a password.

Why is a webhook signed?

A webhook arrives at an address that can be reached from the internet. With the signature, the receiver can check that the message comes from the right sender and was not changed on the way. That only helps if the receiving software actually checks the signature.

Can I connect Service Suite to my accounting package?

If your accounting package can work with an API or with webhooks, it can read data with an API key, such as invoices, and receive notifications, such as a posted invoice or credit note. Who builds the integration is something you agree with the supplier of the package. You ask Digitalnatie for the permission to create keys and webhooks. If the package cannot do this, an export and an import remain the way.

Can anyone create an API key in Service Suite?

No. API keys and webhooks require a technical permission that no role template gives, not even the administrator’s. You ask Digitalnatie for it.