The whole category in one page.
MOST INTEGRATION WORK IS HANDLING FAILURE, NOT CALLING THE ENDPOINT
The happy path is the small part. Timeouts, retries, duplicates, partial failures and reconciliation are the work.
A TIMEOUT MEANS UNKNOWN, NEVER FAILED
The other side may have completed it. Query the status or reconcile — never assume and repeat, particularly with money.
RETRIES ARE CERTAIN, SO MAKE OPERATIONS IDEMPOTENT
Use an idempotency key for anything that creates, and expect duplicate webhooks as normal rather than exceptional.
THE COMMONEST SERIOUS BREACH IS A MISSING OWNERSHIP CHECK
Authenticating the caller is not authorising the object. Test every endpoint as the wrong account, automatically.
NEVER RETURN SUCCESS WITH AN ERROR INSIDE THE BODY
Monitoring then sees nothing wrong while everything fails.
DECIDE WHICH SYSTEM OWNS EACH FACT, AND PREFER ONE-WAY FLOW
Two-way synchronisation needs conflict rules that are always arbitrary.
MONITOR LAST SUCCESSFUL RUN, NOT JUST ERRORS
An integration that silently stopped is the commonest failure and the hardest to notice.
RECONCILE, BECAUSE PARTIAL FAILURE IS NORMAL
VERIFY EVERY WEBHOOK SIGNATURE, ACKNOWLEDGE FAST, PROCESS AFTERWARDS
AND GIVE EVERY INTEGRATION AN OWNER — UNOWNED ONES ARE MAINTAINED BY NOBODY UNTIL THEY BREAK
