Connect other systems (API keys and webhooks)

Another system — an online shop, a booking channel, your accountant's software, a custom app — can work with your BusinessSensor data in two ways:

• An API key lets it read or change data, for example fetch customers or record a sale.
• A webhook tells it straight away when something happens here, such as a payment received, a room booked or stock running low.

Before you start

• You need the Company Settings permission.
• You can only give a key permissions you have yourself.

Steps

Make an API key

1. Go to Setup → Developer & API and open the API keys tab.
2. Click New API key, and give it a name that says who uses it, such as Online shop sync.
3. Tick only the permissions the other system needs. Tick Read-only if it only reads.
4. Choose when it expires, then click Create key.
5. Copy the key and give it to whoever sets up the other system. It is shown only once.

Make a webhook

6. Open the Webhooks tab and click New webhook.
7. Enter the address the other system gave you (it starts with https://), and tick the events it wants to hear about.
8. Click Create webhook. Copy the signing secret and give it to the other system, which uses it to check each message really came from you. It is shown only once.
9. Click Test. A test event is sent at once, and you see what the other system answered.

Tips

• What a key can do: a key acts as the person who made it, limited to the permissions ticked on the key.
  • If that person later loses a permission, or is made inactive, the key loses it too.
  • The key's changes appear in the audit log under that person's name.
• What a key can't do: sign in, change users or security groups, or create other keys and webhooks.
• Revoke a key on the API keys tab as soon as it is no longer needed, or if it may have been seen by someone else. It stops working within a minute.
• Deliveries: opens a webhook's recent messages, whether each was delivered, the exact message sent, and Send again.
• New secret: the key button gives a webhook a new signing secret. Update the other system straight away.
• Get started tab: shows the address to call, a ready-made example, and the link to the full API reference when your server has it switched on.

Common problems

• "You can only give a key permissions you have yourself". Ask an administrator to make the key, or to add the permission to your security group.
• The other system gets "This API key has been revoked / has expired". Make a new key and give it the new one.
• The other system gets "isn't available to API keys" or "read-only". That screen isn't open to keys, or the key is read-only and the system tried to change something.
• "Too many requests" (429). Each key may make a limited number of calls a minute (shown on Get started). The other system should slow down and retry.
• A webhook turned itself off.
  • Either the other system answered 410 Gone, or delivery failed many times in a row (the reason is shown on the webhook).
  • Fix the receiving end, click Edit, tick On and save.
• "The address must be reachable on the internet". Webhooks can't be sent to local or private network addresses. Use the other system's public https:// address.