Skip to content
JC Julián Cardozo
  • Strengths
  • Career
  • Projects
  • Blog
  • GitHub
  • Contact
ES
← Back to the newsletter

Issue 001August 11, 2026Technical case

The hard part of a webhook isn't receiving it

A payment integration breaks less often because it fails to receive events than because it doesn't know what to do with duplicated, out-of-order or ambiguous ones.

Primary audience

CTOs, Tech Leads and fintech teams

Objective

Authority and conversation

Related project

MiCuota.online →

Related article

Payment webhooks and auditable state machines →

There is a scene that repeats itself in many teams: the webhook arrives, returns 200, and someone breathes easy as if the hard part were over.

In payments, that moment is only the beginning. The event can arrive duplicated, out of order or with partial information. If the system can't read it within an explicit state machine, the cost doesn't show up as an elegant technical error: it shows up as a questionable charge, a wrong notification or a manual reconciliation at the end of the day.

Where it really breaks

The problem isn't receiving JSON. The problem is translating an external signal into a valid transition within your model. If the provider says "paid" and you don't distinguish between authorized, captured, reconciled or reversed, the integration becomes optimistic where it should be strict.

At MiCuota.online this matters because the user isn't admiring the code. They're waiting to know whether their fee was recorded, whether the collection succeeded and whether they can trust the system not to duplicate an action because of a late retry.

The decision that limits the damage

The useful decision is to treat the webhook as input to an auditable state machine. Each event is recorded, validated against the current state and only then produces effects: marking a payment, sending a notification or updating a view for the user.

That forces you to model idempotency, correlation and traceability. It also forces you to accept that some events must stay in quarantine until there is enough context. Not everything gets resolved "inline", and not every error should be hidden behind a blind retry.

What you can apply tomorrow

If your integration today mixes event intake, business rules and notifications in the same block, you are probably paying operational debt disguised as speed.

Separating ingestion, validation and effects doesn't make the system slower: it makes it clearer who decided what, with what evidence and on which state.

Practical tool

Minimum checklist to review a payment webhook

  • Is there an explicit state machine for the payment domain?
  • Does each event have an idempotency key or a robust way to deduplicate?
  • Are invalid transitions logged and visible for review?
  • Do notifications go out after the state is confirmed, not before?
  • Is there enough traceability to get from the event back to the affected operation?

Connection to the ecosystem

A webhook isn't a friendly notification: it's an operational edge where a payment system either stays consistent or starts losing trust.

Go to the full technical article See the MiCuota.online case
Reply on this topic

What is the most delicate state transition in your system, and why does it still depend more on luck than on design?

Julián Engineering Manager, product builder and founder of Pambú Tech juliancardozo.github.io · LinkedIn

P.S.: If you're designing subscriptions, billing or reconciliation for Latin America, tell me where the most fragile part of the operation shows up.

Julián Cardozo · 2026

Static site with no frameworks or dependencies: HTML, CSS and a homemade Node generator.

  • Newsletter
  • Privacy
  • GitHub
  • LinkedIn
  • Email