Much integration trouble starts in the meeting that never happened. Someone asks for two systems to be connected, a developer connects them, and six weeks later a customer receives the same receipt twice and nobody knows whose problem that is. An hour with the sheet below prevents a lot of this. Operations should lead decisions one to three and seven, and developers the rest.
One example runs throughout: when a payment is confirmed, send the customer a WhatsApp receipt and mark the invoice as paid.
1. Name the workflow in one sentence
Write the trigger, the action and who benefits. "Connect our accounting system" has no end. "When a payment is confirmed, the customer gets a receipt within a minute and finance sees the invoice as paid" can be tested.
Add what must not happen: no receipt for a failed payment, and never two receipts for one payment. Those lines become your test cases.
2. Decide which system owns each field
Name one system of record for every field. Customer phone number might belong to your CRM, invoice status to accounting, message delivery status to your messaging platform. When two systems can both edit a field and neither wins, they eventually disagree and someone fixes it by hand.
Customers notice. Nielsen Norman Group's omnichannel research says they expect data to stay valid as they move between channels, which needs back-end systems that share and update it.
3. Set the direction and the minimum data
For each field, write which way it flows and when. One-way is easier to reason about, so start there unless the workflow truly needs both.
Then cut the list. Kenya's Data Protection Act requires personal data to be limited to what is necessary for the purpose. The receipt needs a name, an amount and a reference. It does not need a date of birth. If a vendor processes personal data for you, guidance for small businesses from the Office of the Data Protection Commissioner says to check that the vendor is registered and to sign a written agreement.
An API call is you asking another system for something. A webhook is the other system telling you something happened. The rest of this sheet focuses on webhooks, where most surprises live.
4. Verify every incoming webhook
A webhook URL is an address on the public internet. Stripe's documentation spells out the risk: without verification, an attacker could send fake events that trigger actions such as fulfilling orders.
The usual defence is a signature. The sender computes an HMAC of the request body with a shared secret, and you compute it again and compare. Meta's WhatsApp webhooks do this with an HMAC-SHA256 hash in the X-Hub-Signature-256 header, and GitHub's use the same header name.
Details that catch teams out:
- Verify against the raw body. Stripe warns that any change to it makes verification fail.
- Use a constant-time comparison, as GitHub recommends, to reduce timing attacks.
- Reject old messages where the sender gives you a signed timestamp. Stripe's libraries default to a five-minute tolerance.
- Store the secret securely and replace it periodically, or at once if you suspect a leak.
5. Make repeats harmless
Expect the same event more than once. Meta says its retries can result in duplicate notifications, and Stripe says endpoints might occasionally receive an event twice.
RFC 9110 calls a method idempotent if several identical requests have the same intended effect as one. Your handler needs that property: a second payment event must not send a second receipt. Store the unique ID of each event you process and skip any you have seen. Stripe recommends logging event IDs for this, and GitHub provides a unique delivery ID.
The same applies in the other direction. RFC 9110 says clients should not automatically retry a non-idempotent request unless they can tell it is safe. Some APIs give you a way: with Stripe's idempotency keys, you can repeat a request after a connection error without performing the operation twice. Stripe also advises against using personal data in those keys.
Do not depend on order either. Stripe does not guarantee events arrive in the order they were generated, so a paid event may land before the invoice event. Fetch the current state from the source system instead of assuming.
6. Agree how retries behave
When receiving, answer fast and do the work afterwards. GitHub expects a 2XX response within 10 seconds, and Stripe advises returning success before any complex logic. Put the event on a queue, acknowledge it, then process it.
Learn each sender's habits, and recheck them when you build, because they change. At the time of writing, Meta says it retries for up to 7 days when it does not get a 200 response, and Stripe says up to three days in live mode. GitHub's guidance is to redeliver missed webhooks once your server is back. A short outage may heal itself with one sender and leave a gap with another.
When sending, retry with care. Amazon's engineering guidance is to use backoff with jitter, cap the attempts and retry at one layer only, because retries add load to a system that is already struggling. Separate temporary failures, such as timeouts, from permanent ones, such as a rejected number.
7. Name who owns failure
For each failure below, write a person or team, not a system:
- A webhook keeps failing. Who is alerted, and how fast?
- An event has failed all its retries. Where does it land, and who replays it?
- Two systems disagree. Which wins, and who corrects the record?
- A customer got a wrong or duplicate message. Who contacts them?
Keep failed events rather than discarding them, and reconcile daily for anything involving money: compare payments against receipts sent and investigate the gap. Before go-live, ask each vendor for a test environment and a named contact.
Bringing your sheet to Jadility
Jadility's integration ecosystem connects to third-party software, and the Jadility API and webhooks connect your own systems. Bring your finished sheet to a conversation with us and we can go through which connections suit your workflow.
Sources
- Consistency in the Omnichannel Experience, Nielsen Norman Group, accessed 6 November 2026.
- Data Protection Act, 2019, ODPC, accessed 6 November 2026.
- Guidance Note on Processing by MSMEs (archived), ODPC, accessed 6 November 2026.
- Receive Stripe events in your webhook endpoint, Stripe, accessed 6 November 2026.
- Idempotent requests, Stripe, accessed 6 November 2026.
- Webhooks overview, Meta, accessed 6 November 2026.
- Create a webhook endpoint, Meta, accessed 6 November 2026.
- Validating webhook deliveries, GitHub, accessed 6 November 2026.
- Best practices for using webhooks, GitHub, accessed 6 November 2026.
- RFC 9110: HTTP Semantics, IETF, accessed 6 November 2026.
- Timeouts, retries, and backoff with jitter, Amazon Web Services, accessed 6 November 2026.











