“Should we use the API or a webhook?” comes up in almost every integration project. The short answer: they are not competitors. An API lets your system ask another system for data or tell it to do something. A webhook lets the other system tell yours that something has happened. Most reliable integrations use both.
The difference in one sentence each
- API (pull): your server sends a request when it decides to (“give me the orders updated since 10:00”, “create this customer”) and gets a response.
- Webhook (push): the other platform sends an HTTP request to a URL you registered when an event happens (“an order was paid”, “a refund was created”).
Webhook vs API at a glance
| API | Webhook | |
|---|---|---|
| Who starts the exchange | Your system | The other platform |
| When data arrives | When you ask (on demand or on a schedule) | Shortly after the event |
| Direction | Read and write | Notification only (you still use the API to act) |
| Typical use | Create or update records, run searches, catch up after an outage | React to events: payment confirmed, order created, stock changed |
| Main risk | Polling too often (rate limits) or too rarely (stale data) | Missed, delayed, duplicated or forged deliveries |
| What you must build | Authentication, pagination, rate-limit handling | A public HTTPS endpoint, signature verification, duplicate handling |
An e-commerce example: a paid order reaching your accounting tool
Imagine you want every paid Shopify order to appear in your accounting software.
- The webhook announces the event. Shopify sends an order webhook to your endpoint as soon as the order is created or updated.
- Your endpoint answers fast. It checks the signature, records the event and returns a 2xx status straight away. The heavy work happens afterwards, in the background.
- The API does the work. Your service reads the full order through the Shopify Admin API if needed, then calls the accounting software’s API to create the sale or invoice.
- A scheduled API check closes the gaps. Once an hour or once a day, your service asks the Shopify API for recent orders and fills in anything a webhook might have missed.
The webhook gives you speed; the API gives you control and a way to recover. Relying on only one of them is where most integrations break.
Webhooks: what to get right
Verify every delivery
Anyone can send a request to a public URL. Shopify signs its deliveries with an HMAC computed from the raw request body and your app’s secret; your endpoint must recompute it and reject any request whose signature does not match.
Answer quickly, process later
Platforms expect a fast 2xx response. Shopify’s documentation, for example, states that failed order webhook deliveries are retried up to 8 times over 4 hours with exponential backoff, and recommends acknowledging receipt quickly and doing long-running work out of band.
Expect duplicates and disorder
A retry can deliver the same event twice, and two events can arrive in a different order from the one in which they happened. Store an identifier for each processed event and make your processing idempotent: handling the same event twice must not create two invoices.
Never rely on webhooks alone
Endpoints go down, deployments happen, certificates expire. A periodic reconciliation through the API is what makes an integration trustworthy.
APIs: what to get right
Respect rate limits
Every API limits how much you can ask. The Shopify GraphQL Admin API, for instance, uses a calculated query cost with a bucket that refills continuously, and the rate depends on the store’s plan. Ask only for the fields you need and back off when you are throttled.
Keep credentials on the server
API keys and access tokens belong on a server, never in your website’s public JavaScript or theme. Request only the permissions the integration needs.
Plan for change
APIs are versioned. Pin the version you use, follow deprecation notices and test before upgrading.
Which one should you use?
- You need to react within seconds to an event (payment confirmed, order created): webhook, then the API to act.
- You need to create or change data in another system: API.
- You need a nightly export or a report: API on a schedule.
- The other platform offers no webhooks: API polling at a sensible interval.
- Money or stock is involved: both, with reconciliation.
Frequently asked questions
Is a webhook a type of API?
It is often described as a “reverse API”: it uses the same building blocks (HTTP, JSON) but the call goes the other way. In practice, you still need the platform’s regular API to read details or make changes.
Is polling an API bad practice?
Not when it is done at a reasonable interval and within the rate limits. It is the right tool for catching up and for platforms without webhooks; it is the wrong tool when you need near-real-time reactions.
Connecting Shopify, a payment provider and your business tools? See our API integration services and Shopify integrations, or describe your project.