Connect TallyTill to Your Other Apps (API Keys & Webhooks)

This manual is for the person who runs the farm or stand, not for a programmer. If you can copy and paste, you can do everything here.

What integrations are for

Your products and stock live in TallyTill. Other things you use, such as your farm website, a spreadsheet or a bookkeeping tool, live somewhere else. Integrations let them talk to each other, so you stop typing the same numbers twice. There are two pieces:

• An API key lets another app ask TallyTill for your products and stock. For example, a farm website that shows what is in stock today. A key that can also write can adjust stock counts.
• A webhook works the other way round. TallyTill tells another app when something happens: stock changes, an item runs low, a sale completes, or a product is added, changed or removed.

You usually do not need both. The other app's instructions will say which it wants.

A Zapier app is coming, but it is not built yet. Creating products through the API is not built either.

Who can set it up

Only people with the Admin role in the Portal can make keys and webhooks. If you do not see the page, ask an Admin on your team.

Everything is under Settings, then API & webhooks. The page has three tabs: API keys, Webhooks and Delivery log.

Make an API key

1. Open Settings, then API & webhooks, then API keys.

2. Choose Create API key.

3. Give it a name that says what will use it, such as "Farm website".

4. Choose the access:

   • Read only: the app can see products and stock.
   • Read & write: the app can also adjust stock.

   Pick read only unless the other app really needs to change your counts.

5. Optionally choose when the key expires: "Never", "In 30 days", "In 90 days" or "In 1 year".

6. Choose Create key.

The key is shown once. Copy it straight away and paste it into the other app. TallyTill keeps only a fingerprint, so it cannot show the key to you again. If you lose it, revoke it and make a new one.

You can rename a key later. To switch an app off, choose Revoke on its row. The app stops working at once, and a revoked key cannot be brought back; make a new one and paste it into the app instead. Revoking a key does not touch your webhooks.

Add a webhook

1. In the other app, find where it gives you a webhook address (a URL). It must start with https://.
2. In TallyTill, open Settings, then API & webhooks, then Webhooks, and choose Add webhook.
3. Give it a name, such as "Farm website".
4. Paste the address into URL.
5. Tick the events you want that app to hear about: stock changed, stock low, sale completed, product created, product updated, product deleted. Tick only what the app needs.
6. Choose Add webhook.

TallyTill now sends a test message to the address to check that it is real and listening. Nothing else is sent to the address until that check passes.

You are then shown a signing secret. The other app uses it to check that each message really came from TallyTill. Copy it into the other app. Unlike an API key, you can show it again later: open the webhook's Edit panel and use the eye button.

"Not verified yet" and the Test button

A webhook that has not passed the check shows Not verified yet. That usually means the other app did not answer the test message, most often because the address was pasted wrongly or the other app is not ready yet.

1. Open Edit and compare the address with the one in the other app. Fix it and save; saving a changed address runs the check again.
2. If the address is right, make sure the other app has finished its own setup, then choose Test on the webhook's row. If the other app answers, the webhook becomes active.
3. Still stuck? Open the Delivery log to see what the other app answered, and pass that on to whoever supports the other app.

On a webhook that is already active, Test sends a test message and shows you the answer without changing anything. Test messages do not use up any free allowance.

Read the delivery log

Settings, then API & webhooks, then Delivery log lists the messages TallyTill sent. Each row says:

Choose View on a row to see exactly what was sent and what the other app answered. You can filter by event, by webhook or by result. The log keeps the last month.

Retrying

If another app is down, TallyTill keeps trying a message for about three days, and a webhook that keeps failing is paused. For a message that gave up, choose Retry on its row once the other app is healthy again, and it is sent straight away. Resume or Test the webhook first if it is paused or not verified; Retry only works on an active webhook.

Pausing and resuming

TallyTill pauses a webhook for you in two cases: the other app has failed for three days in a row (your Admins are emailed), or it answered that the address is gone for good. Nothing is sent to a paused webhook.

Once the other app is working again, choose Resume on the row. Messages that arrived while it was paused are not sent afterwards, so to catch up, have the other app read your products and stock again through the API. If you no longer want a webhook at all, choose Delete: that also deletes its delivery log, and it cannot be undone.

The Stand plan's free daily allowance

Every plan can use API keys and webhooks. The Stand plan is free, and it includes a small free daily allowance of webhook messages and API calls. The Portal shows today's usage as a meter at the top of the page, with the time it resets. On Stand, once the day's allowance is used, further webhook messages are skipped (they show in the delivery log as over the free limit and are not sent later) and further API calls are refused until it resets. Shop and Market do not use this allowance. If you reach it often, See plans on the meter compares the plans, or see our pricing page.

Keep keys and secrets safe

• Treat an API key like a password. Paste it only into the app that needs it, never into an email, a chat or a public page.
• Make one key per app and name it, so you know what to revoke if something goes wrong.
• Give a key read-only access unless the app must change stock.
• If a key or secret might have leaked, act at once. Revoke the key and make a new one. For a webhook secret, open Edit and choose Rotate: the new secret signs straight away and the old one also signs for 24 hours, so you have time to update the other app.
• Revoke keys and delete webhooks for apps you no longer use.
• Set an expiry on keys made for short projects.

For the person who builds it

If someone is building the connection for you, tell them TallyTill offers a REST API for reading products and stock and adjusting stock (adjusting needs a read & write key), and signed webhooks that follow the Standard Webhooks specification. The API reference, with every endpoint and examples, is published at /api/v1/docs on TallyTill's API.