Smart API

The Smart API provides all the endpoints required to create an integration. It is designed for server-to-server integrations and not for native or web applications for end users. Therefore, it only provides API keys for authentication. Go to the Smart API documentation or download the OpenAPI specification of the Smart API to get started.

Webhooks are the preferred method for creating integrations that expect event-driven information from the Smart API. The other option would be to query a Smart API endpoint at a specific interval, which would place a greater load on the Smart API and the system that sends the requests.

The Smart API provides webhooks via automations and allows webhooks to be set up for selected events only or for all events.

How do webhooks work?

Webhooks vs. Websockets

Webhooks should not be confused with websockets. Webhooks are notifications that are sent from one server to another, while websockets enable real-time communication between servers and clients.

Schurter Smart API signs webhook requests by generating a hash-based message authentication code (HMAC) with SHA-256.

To validate the requests received by your platform, follow the steps below:

Extract the timestamp and signature from the header called X-Signature (e.g. v=1;t=1701252447;sig=0102030405060708).

Create the same string as was used to generate the signature by concatenating the timestamp, the character . and the received UTF-8 encoded request body (e.g. 1701252447.SampleRequestBody).

Generate an HMAC with SHA256 of the concatenated UTF-8 encoded string. Use the webhook signing secret as the key.

Compare the the received signature with the generated signature. If the signatures match, check if the received timestamp is within your tolerance (e.g. 5 minutes).