In this guide · 8 sections
- 01What is an API? The simple version
- 02What is a webhook? API vs webhook compared
- 03A real example: a Stripe payment reaching Xero
- 04API keys: the password you must not leak
- 05Rate limits, errors and why integrations break
- 06What to ask a vendor about their API
- 07Do it yourself or get help?
- 08Frequently asked questions
Short answer
An API is a door one app opens so another app can ask it for data or tell it to do something (you pull). A webhook is the app knocking on your door the moment something happens, such as a payment succeeding (it pushes). Most integrations use both.
What is an API? The simple version
API stands for application programming interface. Think of it as a service counter: your app walks up with a request in a fixed format ("give me all invoices from this week", "create a customer called X") and the other app answers in a fixed format. The counter has rules about who may ask, what they may ask for and how often.
When software says it "integrates with Xero" or "connects to Google Calendar", it almost always means it uses that product's API. If a product has no API, the only ways to move data in and out are manual exports, email parsing or screen-scraping, all of which break easily.
What is a webhook? API vs webhook compared
A webhook turns the API around. Instead of your app asking every few minutes "any new payments yet?", the other app sends a message to a web address you give it as soon as the event happens. Zapier's help centre describes webhooks as notifications.
API call (pull)
- Your system asks when it wants data
- Good for looking things up or creating records
- Asking too often wastes requests and hits rate limits
- Works even if you were offline earlier
Best for: Reading or changing data on demand.
Webhook (push)
- The other system tells you the moment something happens
- Near real-time: payment paid, form submitted, booking made
- Your endpoint must be online and must check the sender
- Can arrive twice or out of order
Best for: Reacting to events as they happen.
Most real integrations use both: a webhook says "invoice 123 was paid", then your system calls the API to fetch the full invoice details.
A real example: a Stripe payment reaching Xero
Say you take card or PayNow payments through Stripe and keep your books in Xero. Here is what happens behind the scenes when a customer pays, whether you use Xero's own Stripe connection, Zapier or a custom build.
The customer pays on Stripe's checkout
Stripe records the payment and creates an event, for example checkout.session.completed.
Stripe sends a webhook to your endpoint
Stripe POSTs the event to the URL you registered. Its webhook docs say the receiver should verify the Stripe-Signature header with the endpoint's signing secret before trusting it.
Your endpoint replies quickly
Stripe asks for a 2xx response before any slow work, such as updating the invoice in your accounting system, so the delivery doesn't time out.
Your system calls the Xero API
It finds the matching invoice in Xero and records the payment against it, using Xero's API with a connection you authorised.
If anything fails, Stripe retries
In live mode Stripe retries delivery for up to three days with exponential back-off, and you can resend events from the Dashboard.
Stripe also warns that events are not guaranteed to arrive in order and can arrive more than once, so a good integration logs event IDs and ignores repeats. That is the difference between a quick script and one you can rely on at month-end. Our payment gateway integration guide covers testing this before launch.
API keys: the password you must not leak
To use an API, your system proves who it is with an API key or a login token. Whoever has the key can act as your business on that service. Stripe's API keys page is a good model of the rules.
- Publishable keys (Stripe's start with pk_) are designed to sit in your website's browser code. Only these are safe to expose.
- Secret keys (sk_) can do everything on the account. Stripe no longer recommends them for new uses and suggests moving to restricted keys.
- Restricted keys (rk_) carry only the permissions an integration needs, such as reading payments, which limits the damage if one leaks.
- Stripe advises rotating keys when team members with access leave.
Rate limits, errors and why integrations break
Every API limits how many requests you can send. Stripe's rate limits page says the global limit is 100 requests per second per account in live mode and 25 in a sandbox, with lower limits on some endpoints. Go over and you get a 429 Too Many Requests error. A small business rarely hits that, but a badly written sync that loops can.
Other common reasons an integration stops: a key was rotated and not updated, a user who authorised the connection left the company, the vendor changed its API version, or the webhook URL moved when the website was rebuilt. Each one is silent unless someone gets an alert, so ask who is notified when a sync fails.
What to ask a vendor about their API
Before you choose a booking, POS, CRM or membership system, ask these questions. A vendor with good answers will save you money on every future integration.
Questions before you buy
If you'd rather not code, automation tools such as Zapier and Make wrap APIs and webhooks in a visual editor. Zapier's help centre lists Webhooks by Zapier as available on Professional, Team and Enterprise plans, not Free. Our Zapier vs Make comparison has dated prices.
Do it yourself or get help?
If both apps already have a ready-made connection, or a Zapier or Make template does what you need, set it up yourself and test it with a real transaction. You need a developer when there is no ready connector, when money or customer access depends on the result, or when webhooks must be verified and deduplicated.
Our Workflow Automation package (S$390 per workflow) builds and tests one connection in your own Zapier, Make or n8n account. For integrations with signed webhooks, a database or a portal, our Custom Tool or Dashboard work starts from S$1,990 with a fixed written scope; see our custom web app guide for what that involves.
Frequently asked questions
An API waits for your system to ask for data or to request an action. A webhook is the other system sending your system a message automatically when something happens, such as a payment succeeding or a booking being made. APIs are pull, webhooks are push. Most integrations combine them: a webhook announces the event and an API call fetches the details.
Not always. Tools such as Zapier and Make can receive a webhook and pass the data to hundreds of apps without code, though Zapier's webhook feature needs a paid plan. You need a developer when the webhook must be verified for security, when duplicates must be handled, or when payments or customer access depend on it working.
It depends on the sender. Stripe retries failed webhook deliveries for up to three days with increasing gaps in live mode, and you can resend events from the Dashboard. Some smaller vendors retry only a few times or not at all, so ask before you rely on them, and set an alert for failed deliveries.
Only if it is a key designed to be public, such as Stripe's publishable key. Secret and restricted keys must stay on the server or in your hosting platform's secret settings. Anyone who sees a secret key in your page source can use your account. If a key has been exposed, rotate it immediately and update your systems.
Error 429 Too Many Requests means you have sent more API requests than the service allows in a period. Stripe, for example, allows 100 requests per second per account in live mode. Well-built integrations slow down and retry when they see a 429. Repeated 429s usually mean a sync is looping or polling too often.