Two processes refreshing the same user
How you'll know: One worker succeeds, the other gets an invalid-token error, and soon nothing can refresh.
Fix: Refresh tokens are one-time-use, only one is valid per user per app, and every new bearer token voids the old refresh token. Let one job refresh, and save the new refresh token before anything else uses it.
A webhook that was registered but never verified
How you'll know: The callback exists, and no events ever arrive.
Fix: After you POST to the callbacks endpoint, FreshBooks posts a verification code to your URI. PUT it back to /events/callbacks/{callback_id} as the verifier. A PUT with resend: true asks for a fresh one.
Signatures that never match
How you'll know: Every delivery fails your check against X-FreshBooks-Hmac-SHA256.
Fix: The verifier is the signing secret. The signature is base64, over the parameters as a JSON string with values cast to strings, and spacing matters: Python's json.dumps adds spaces after colons and commas, and dropping them changes the result.
A handler that does the work before it answers
How you'll know: Deliveries retry, some vanish, and eventually the webhook is switched off.
Fix: FreshBooks waits ten seconds and treats anything but a 2xx as failure. It retries, then drops the message, and can disable a webhook that keeps failing. Reply at once, process afterwards, and resend verification to switch it back on.
Treating the payload as the record
How you'll know: Your code expects invoice details and gets a handful of IDs.
Fix: Deliveries carry the event name, object_id, account_id and business_id as form fields. Fetch the object from the API with that ID.