API integrations are how one piece of software talks to another: your online shop telling your accounting system about a sale, or a payment provider telling your app that a customer has paid. Founders do not need to write this code, but they do need to understand a few ideas, because integrations are where many outages, surprise bills and security problems begin. This guide covers the three that come up most: webhooks, keys and rate limits.
APIs in one paragraph
An API (application programming interface) is a set of addresses and rules that lets one system ask another for something. Your app sends a request, such as “create this invoice” or “give me today’s orders”, and gets a structured reply. The provider publishes documentation listing what you can ask for, what you must send and what comes back. If a service has good API documentation, connecting to it is usually predictable work. If it has none, budget for investigation before anyone can quote.
Webhooks: when the other system calls you
An API call is your system asking. A webhook is the other system telling you, without being asked, that something happened. You give the provider a web address on your server, and it sends a message there whenever a chosen event occurs: a payment succeeds, a subscription is cancelled, a parcel is delivered.
Webhooks save your app from checking every few minutes, but they bring their own rules. Stripe’s webhook documentation is a good model of what careful handling looks like, and most of it applies to other providers too.
- Verify the sender. Stripe signs each event and tells you to check that signature against a secret before acting on it. Without that check, an attacker could send fake events, for example to mark an order as paid.
- Reply quickly. Stripe asks endpoints to return a success code before running any slow work, and to queue the rest.
- Expect repeats. Stripe retries failed deliveries in live mode for up to three days, and says the same event can occasionally arrive more than once. Record the event IDs you have processed and ignore duplicates.
- Do not rely on order. Stripe does not guarantee events arrive in the order they happened, so your code should cope if “invoice paid” arrives before “invoice created”.
API keys: the passwords of integrations
Most APIs identify your system with a key, a long string that works like a password. Anyone who has your secret key can act as your business with that provider, which might mean issuing refunds, reading customer data or running up usage charges.
- Keep secret keys on the server, in environment variables or a secrets manager. Never put them in code that runs in the browser or a mobile app, and never in a code repository.
- Use separate keys for testing and live use. Stripe, for example, gives test and live modes different keys and different webhook secrets.
- Give each key only the permissions it needs, where the provider allows restricted keys.
- Rotate keys when someone with access leaves, and immediately if a key may have leaked. Stripe also recommends rolling webhook signing secrets periodically.
- Keep the accounts in the company’s name, so keys are never tied to one person’s login.
Keep a simple register of every integration: the service, what it is used for, who owns the account, where the key is stored and when it was last rotated.
Rate limits: how much you can ask, how fast
Providers limit how many requests you can send in a period, to protect their systems. When you exceed the limit, the standard response is HTTP status 429, which RFC 6585 defines as the user having sent too many requests in a given amount of time. The response may include a Retry-After header saying how long to wait, but it is optional.
In practice, rate limits bite at the worst moments: a big import, a sale day, the first of the month when every subscription renews. Say a retailer in Melbourne syncs 20,000 products to a marketplace overnight and the sync stops halfway. Well-built integrations slow down and retry with growing pauses when they receive a 429, process large jobs in batches and log what failed so it can be resent.
Ask your developer three questions about every integration: what happens when the other side is down, what happens when we hit a limit, and how would we know? Clear answers are a good sign.
Where API integrations fit in your business
Many integrations exist to remove manual work: copying orders into accounts, sending confirmations, updating stock. Our automation service focuses on that kind of work, and integrations inside a product you are building fall under our SaaS and web app service.
Frequently asked questions
What is the difference between an API and a webhook?
With an API call, your system asks another system for something and gets a reply. With a webhook, the other system sends your system a message when an event happens, without being asked. Many integrations use both: webhooks to hear about changes as they happen, and API calls to fetch details or make updates.
What should I do if an API key leaks?
Revoke or rotate the key in the provider’s dashboard straight away, then update your app with the new key. Check the provider’s logs for activity you do not recognise, such as refunds or data exports. Remove the key from any code, documents or chats, and find out how it leaked so the same route is closed.
What does a 429 error mean?
HTTP status 429 means Too Many Requests: your system has sent more requests than the provider allows in a given period. The fix is usually to slow down, wait as long as any Retry-After header says, and retry. If it happens often, batch requests, cache results or ask the provider about higher limits.