Settings

API & Webhooks

What the Salonnare API and webhooks are, and step by step how to create an API key and set up a webhook.

6 min read6 sectionsAlso in 8 other languages
In Settings (13 articles)
On this page

With the API and webhooks you connect your salon to other software, such as your accounting package, your own website or a dashboard you built yourself. You don't need to be a developer to understand what they do; this page explains it and shows how to create a key and a webhook.

Not available yet

This feature is still marked Coming soon in the app: you can't create API keys or webhooks at the moment. If you open Settings > Advanced > API & Webhooks, you only see a message that the feature is on its way. This page describes how it works once the feature is switched on for your salon.

What is an API?

An API is an agreement that lets two programs talk to each other. Where you open a list of appointments in the app, another program can fetch the same data through the API, automatically and without anyone stepping in. For example: your accounting software fetches your appointments every night, or your website shows your treatments and prices straight from Salonnare.

Access goes through an API key: a secret code that proves a request comes from your salon. Treat that key like a password.

Create an API key

Only an admin can create and delete keys.

  1. Step 1: Open API & Webhooks and click New key

    Go to Settings > Advanced > API & Webhooks. On the API keys tab (1), click New key (2).

    The API keys tab with the New key button highlighted (Enlarge image)
  2. Step 2: Give the key a name and choose what it may read

    Enter a recognisable Name, for example the name of the integration (1). Under What may this key read? tick only the data the integration needs (2): Appointments, Clients, Services or Staff. If the key should stop after a certain day, choose a date under Expires. Click Create (3).

    An API key can only fetch data, never change anything. Clients is personal data: only turn it on if your integration partner really needs it. A website that shows your services and prices only needs Services and Staff.

    The New API key window with the name, the read permissions and the Create button highlighted (Enlarge image)
  3. Step 3: Copy the key

    The full key (1) is shown only once. Click the copy button (2) and pass the key on to your integration partner, or store it in a password manager. Then close the window.

    The API key created window with the key and the copy button highlighted (Enlarge image)
  4. Step 4: Your key in the list

    The list shows the name, the start of the key, what it may read, when it was last used and when it expires (1). Renew (2) gives you a new key with the same name and permissions; you choose how long the old one keeps working (stop immediately, 24 hours or 7 days), so your integration partner has time to switch. Revoke (3) stops a key immediately.

    The API keys list with the new key and the Renew and Revoke buttons highlighted (Enlarge image)

What is a webhook?

A webhook is the reverse of the API. Instead of a program repeatedly asking whether there is anything new, Salonnare itself sends a message to an address (URL) as soon as something happens. Salonnare can send these seven events:

  • booking.created: a new appointment is added: in the app, through your online booking page or widget, through Reserve with Google, or as soon as a booking request is confirmed (also every appointment a repeating series creates)
  • booking.updated: a staff member changes an appointment in the app (including a status change to completed or no-show)
  • booking.cancelled: a staff member cancels an appointment in the app
  • payment.received: a staff member checks out at the point of sale
  • client.created: a staff member creates a client in the app
  • client.updated: a staff member changes client details in the app
  • client.deleted: an employee deletes a client in the app. The notification only contains the client number; Salonnare then keeps earlier notifications about that client without name and contact details
Only what happens in the app

Every event comes from an action by a staff member in the app. An online booking through your booking page or Google, a client who cancels themselves, a waitlist entry that gets converted, a recurring series, a treatment course and a client who creates themselves on the booking page do not send a notification. Your integration partner catches those by regularly fetching the list of appointments.

Set up a webhook

  1. Step 1: Open the Webhooks tab

    Go to Settings > Advanced > API & Webhooks and click the Webhooks tab.

    API & Webhooks with the Webhooks tab highlighted (Enlarge image)
  2. Step 2: Click New webhook

    Click New webhook.

    The Webhooks tab with the New webhook button highlighted (Enlarge image)
  3. Step 3: Enter the address and choose the events

    At URL, enter the address you received from your integration partner; it starts with https:// (1). Tick the events the integration should respond to (2 and 3). Active is on by default. Click Save (4).

    The New webhook window with the URL, two ticked events and the Save button highlighted (Enlarge image)
  4. Step 4: Copy the secret

    Salonnare signs every message with a secret, so the receiver can check that it really comes from your salon. The secret (1) is shown only once: copy it (2) and pass it on to your integration partner.

    The Webhook secret window with the secret and the copy button highlighted (Enlarge image)
  5. Step 5: Test and view the messages

    The webhook is now in the list (1). With Test (3) Salonnare immediately sends a test message and you see whether it arrived. Under Messages (4) you see every message with its status (delivered, being retried or failed) and its attempts; you can resend a failed message there with Resend. If you have lost the secret, click New secret (2); the old one stops working, so the receiving side has to be updated too.

    The webhook in the list with the New secret, Test and Messages buttons highlighted (Enlarge image)

What if ...

... the test doesn't arrive? Then Salonnare tells you that the address did not respond, or which error code the receiver returned. Check the address and ask your integration partner to look at why their side rejects the message.

... a notification doesn't arrive once? Salonnare tries again: after about 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours and 24 hours. Every attempt carries the same notification number, so the receiver recognises a notification that arrives twice. If no attempt succeeds and nothing else got through in that time either, Salonnare switches the webhook off and lets you know with a notification. You switch it back on by editing it and turning Active on. You can resend failed messages under Messages with Resend.

... the address is rejected? A webhook must point to a public address. Salonnare rejects addresses in an internal or private network, localhost and addresses that don't start with https://, with a message that says what is wrong.

... you suspect a key has leaked? Delete it straight away with the bin icon and create a new one.

Working safely

  • Never share API keys and webhook secrets publicly (not in a plain email, on a screenshot or in code that is online).
  • Give an integration only the permissions it needs.
  • Delete keys and webhooks you no longer use.

Are you a developer looking for the technical details (authentication, endpoints, fields, signatures)? See the API Reference.

Was this helpful?

Your answer helps us improve the guides.

Still stuck?

Support: Mon-Fri reply within 24 to 48 hours (Pro: within 24 hours) · weekends and public holidays: within 24 hours if urgent, otherwise on the next business day

Contact us