How is a custom API integration built?
You decide how the two systems will notify each other, authenticate safely, map the data both ways, handle the failures that are certain to happen, test it against real records, and put monitoring on it. The code is the small part.
- Trigger: a webhook if the system supports one, polling on a schedule if it does not
- Authentication: credentials scoped to only what the integration needs, stored where code cannot leak them
- Mapping: which system owns each field, and what happens when both change the same record
- Failure handling: retries that back off, and a place failed items go so nothing vanishes
- Monitoring: someone finds out it broke before a customer does
The first decision: webhooks or polling
Everything else follows from how the integration learns that something happened. There are only two options, and most systems support one of them better than the other.
| Webhooks | Polling | |
|---|---|---|
| How it works | The other system calls you the moment something happens | You ask it on a schedule whether anything changed |
| Speed | Near instant | As fresh as your schedule, so minutes at best |
| Running cost | One call per real event | Constant calls, most of which find nothing |
| Risk | A missed delivery is gone unless the sender retries | Slower, but you can always re-ask |
| Use it when | The system offers them and speed matters | No webhooks exist, or you need a safety net alongside them |
The pragmatic answer is often both: webhooks for speed, plus a slow poll a few times a day to catch anything the webhooks dropped. That combination costs very little and removes the worst failure mode, which is data quietly going missing.
Authentication, and where credentials belong
Most systems use an API key or OAuth. The mechanism matters less than two habits that separate a professional build from a risky one.
First, scope the credential to only what the integration needs. A key that can read and write everything is convenient during development and a liability forever afterwards.
Second, keep it out of the code. Credentials belong in the platform's own secret storage or an environment variable on the server, never committed to a repository and never in a spreadsheet emailed between people. A key in a repository is a key you have to assume is public.
What breaks, and designing for it
Integrations do not fail because the code was wrong on day one. They fail because something around them changed, and the ones that survive are the ones built expecting it.
Rate limits. Every API has them, and hitting one returns an error rather than your data. The fix is retrying with increasing gaps rather than immediately, which stops you hammering a system that is already refusing you.
Duplicates. If a delivery is retried, the receiving system may process it twice, and one enquiry becomes three contacts. The defence is making each operation safe to repeat, usually by carrying a unique reference the receiver can recognise.
Silent changes. A field gets renamed, an API version is deprecated, a credential expires. None of these announces itself, which is why the monitoring below is not optional.
Testing an integration properly
Testing with tidy sample data proves almost nothing. Real records are the test that matters, and specifically the awkward ones: the contact with no surname, the order with forty line items, the phone number typed into the name field.
Use a sandbox where the system offers one, and where it does not, test against real data you are willing to make a mess with rather than a live customer record.
Then deliberately break it. Turn off the credential and check what happens. Send a malformed payload. If the answer to either is "nothing visible", the integration is not finished.
Monitoring, and who gets told
An integration nobody is watching is a liability rather than an asset, because the failure mode is silence. Data stops flowing, nothing shouts, and someone notices three weeks later when a customer asks about an invoice that never arrived.
Useful monitoring answers two questions: is it still running, and did anything fail that a person needs to see. Failures should land somewhere a human actually looks, not in an inbox rule nobody reads.
That ongoing watch is what our maintenance service covers, and it is the part most people discover they wanted only after they needed it.
Where AI fits into an integration
A traditional integration moves structured data. It cannot handle an email, a PDF or a free-text form, so anything unstructured has always stopped at a person.
An AI step changes what the integration can accept: reading a document and pulling out the line items without a fixed template, classifying an incoming message, summarising a thread before it reaches someone.
The rule stays the same as everywhere else we use it: AI reads and drafts, deterministic code handles anything irreversible. If the whole idea is new, start with what AI automation actually is, or see how we build it as AI automation.
Build or buy, honestly
Everything above is worth doing only when a custom build is the right answer, and often it is not. If both systems are mainstream, a ready-made connector through workflow automation does the job in a fraction of the time, and our comparison of Zapier, Make and n8n covers which one.
Custom earns its cost in three cases: no connector exists, the connector exists but does not carry the fields you need, or the volume is high enough that per-task pricing costs more than owning the code.
Deciding which of those you are in is the job of API integration consulting, and it happens before anyone writes anything. What it all costs is on our answers page.
Custom integration questions, answered
How long does a custom API integration take to build?
A single integration between two modern, well-documented systems is usually days. The number grows with the age and stubbornness of the systems involved rather than the size of your business: an internal tool with no documentation and no test environment can take longer than five modern ones put together.
What is the difference between a webhook and polling?
A webhook means the other system tells you the moment something happens. Polling means you ask it repeatedly whether anything has changed. Webhooks are faster and cheaper to run, polling is more forgiving when the sending system is unreliable, and plenty of integrations use both.
Where should API credentials be stored?
Never in the code, and never in a spreadsheet someone emails around. They belong in the platform's own secret storage or an environment variable on the server, scoped to only the permissions the integration actually needs. A key that can do everything is a key that can break everything.
What happens if the other system goes down?
A well-built integration retries with increasing gaps rather than hammering a system that is already struggling, and gives up after a sensible number of attempts rather than silently forever. Anything it could not deliver should be visible somewhere a person will look.
Can you take over an integration someone else built?
Yes, and it is a common request. The first step is reading it and telling you what state it is in, including the parts we would not have built that way. Quoting a rewrite before understanding the existing system is how both sides end up unhappy.
