API Tokens and Webhooks
Letting another system read or write your shop, and telling it when something happens.
Two different jobs. An API token lets another system ask your shop questions. A webhook lets your shop tell another system that something happened.
Both need a higher plan
If API Tokens or Webhooks are missing from Settings, that is why. See What Your Plan Includes.
API Tokens
Settings, API Tokens. A token is a long secret string that identifies a system rather than a person.
Create one per system that needs access, named so you can tell them apart later: Warehouse, Accounts, Stock App. One token shared between three systems cannot be revoked without breaking all three.
The token is shown once
Copy it when it is created. It is stored in a form that cannot be read back, so if it is lost the only option is to delete it and issue another.
A token can be deleted at any time, which stops that system immediately. Do that the moment a system is retired, or a contractor finishes, rather than leaving a working key in somebody's notes.
What the API Can Do
Read and write products, orders, customers and inventory, at /api/v1.
The full reference, generated from the code so it cannot drift from the real behaviour, is at /docs/api on your own shop.
Webhooks
Settings, Webhooks. A webhook sends a message to an address you give when something happens.
| Event | Fires when |
|---|---|
| Order placed | A new order is created |
| Order shipped | Tracking is recorded |
| Order refunded | A refund is issued |
| Order cancelled | An order is cancelled |
| Customer registered | An account is created |
The message carries the detail of the thing that happened, so the receiving system does not have to come back and ask.
Why a Webhook Rather Than Polling
A system that asks every five minutes whether anything has happened is wrong for five minutes and wasteful for the rest. A webhook arrives when it arrives.
The practical answer for anything important is both: a webhook for speed and a periodic check for the ones that went missing, because no webhook delivery is guaranteed forever.
Securing a Webhook
Your endpoint should check that a message really came from your shop before acting on it, using the signature sent with it. An endpoint that acts on anything posted to it is an endpoint anybody can post to.
Use HTTPS. A webhook contains customer names and addresses.
Failures and Retries
A delivery that fails is retried. An endpoint that is down for a while will catch up; one that is permanently gone eventually stops being tried.
If a system has stopped receiving, check whether the endpoint is actually answering before assuming the shop stopped sending. The usual cause is a certificate that expired or a URL that moved.
Testing
Point a webhook at a request-capture service first and place a real order. That shows you the exact shape of the message before you write anything to consume it.
Then point it at your own system and place another. Testing against documentation rather than the real message is how a field name gets assumed and the integration breaks on the first live order.