Webhook Idempotency cho Payment Systems: chống double-charge, duplicate event và side effect lặp trong production

Trong hệ thống thanh toán, bug đắt nhất thường không phải là request timeout. Nó là side effect lặp: trừ tiền hai lần, tạo hai đơn hàng, gửi hai email xác nhận, mở hai subscription hoặc reconcile sai doanh thu vì cùng một payment event được xử lý nhiều lần.

Lý do rất đơn giản: phần lớn payment gateway, webhook provider và message bus trong đời thực đều thiên về at-least-once delivery, không phải exactly-once. Nếu backend của anh coi mỗi webhook arrival là một sự kiện “mới chắc chắn”, production sớm muộn cũng trả giá.

Đây là chỗ nhiều team hiểu sai idempotency. Họ nghĩ chỉ cần client gửi Idempotency-Key khi gọi API tạo payment là xong. Nhưng ở payment systems, rủi ro lớn thường xảy ra sau request ban đầu:

• gateway retry webhook vì endpoint trả chậm hoặc timeout;
• network split khiến provider không biết mình đã giao event thành công chưa;
• backend scale ngang và nhiều worker cùng giành xử lý một event;
• operator replay event để backfill hoặc sau incident;
• downstream service như ledger, email, fulfillment, subscription cùng nghe một event đã duplicate.

Bài này đi sâu vào webhook idempotency trong payment systems dưới góc nhìn production engineering: vì sao exactly-once gần như là một lời hứa nguy hiểm, phân biệt API idempotency với event-processing idempotency, thiết kế deduplication store, xử lý race condition khi nhiều worker cùng nhận event, cách gắn state machine với payment lifecycle, và một playbook đủ thực dụng để tránh double-charge hoặc side effect lặp ở production.

Bài toán thật: payment event gần như luôn là at-least-once

Nhiều provider không hứa “chúng tôi sẽ chỉ gửi webhook một lần”. Họ hứa điều thực tế hơn: nếu không nhận được ACK đáng tin, họ sẽ retry. Về mặt độ tin cậy giao hàng, đây là lựa chọn hợp lý. Nhưng nó đẩy trách nhiệm idempotency sang phía consumer.

Trong payment domain, vài trường hợp duplicate rất phổ biến:

• provider gửi lại cùng một payment.succeeded event sau timeout 5xx hoặc network reset;
• cùng transaction có nhiều event trạng thái nối tiếp nhau, nhưng order arrival không đảm bảo tuyệt đối;
• reconciliation pipeline re-import dữ liệu từ gateway và vô tình kích hoạt lại side effect;
• team vận hành chạy manual replay sau incident để sửa dữ liệu thiếu.

Nếu hệ thống không có lớp chặn duplicate tốt, cùng một sự kiện thành công có thể kéo theo hàng loạt side effect lặp:

• cộng tiền ví hai lần;
• chuyển trạng thái order từ pending sang paid nhiều lần kèm các workflow downstream khác nhau;
• ghi ledger duplicate;
• tạo invoice/receipt duplicate;
• kích hoạt subscription thêm một chu kỳ;
• phát hành entitlement hai lần.

Trong payment, duplicate handling không phải edge case. Nó là yêu cầu mặc định.

Đừng nhầm API idempotency với webhook idempotency

Hai khái niệm này liên quan nhưng không thay thế cho nhau.

API idempotency

API idempotency thường áp dụng khi client hoặc frontend gọi backend để tạo payment intent, charge request, refund hoặc payout. Client gửi Idempotency-Key, backend hoặc payment provider dùng key này để đảm bảo cùng một logical request không tạo nhiều side effect nếu bị retry.

Ví dụ:

• mobile app timeout khi gọi POST /payments;
• app retry với cùng Idempotency-Key;
• backend trả lại cùng kết quả logic thay vì tạo charge mới.

Webhook idempotency

Webhook idempotency xảy ra ở chiều ngược lại: provider gọi vào backend của anh. Lúc này anh là consumer của một event stream. Điều anh cần bảo vệ không chỉ là đã thấy event này chưa, mà là đã apply side effect tương ứng chưa.

Nhiều hệ thống có API idempotency khá tốt nhưng vẫn dính double-processing vì webhook handler còn viết kiểu:

1. parse payload;
2. tìm order theo transaction id;
3. update status sang paid;
4. insert ledger entry;
5. send email;
6. trả 200 OK.

Nếu cùng webhook chạy lại đúng flow này thêm một lần, hệ thống vẫn hỏng dù request tạo payment ban đầu từng được bảo vệ bằng idempotency key.

Exactly-once trong payment processing thường là myth ở mức hệ thống

Đây là điểm mình thấy cực kỳ đáng nói: nhiều team cố “thiết kế exactly-once” nhưng thật ra chỉ chuyển vị trí duplicate từ lớp này sang lớp khác.

Anh có thể đạt exactly-once ở một số scope hẹp như:

• một database transaction ghi đúng một row với unique constraint;
• một message broker feature trong điều kiện cụ thể;
• một consumer group offset commit kết hợp write theo pattern xác định.

Nhưng ở mức end-to-end payment system, thứ anh thật sự có thường là:

• at-least-once delivery;
• idempotent consumer;
• state transition có guard;
• reconciliation để sửa lệch còn sót.

Vấn đề không phải là khẩu hiệu exactly-once. Vấn đề là side effect business của anh có an toàn khi duplicate, retry, out-of-order hoặc replay hay không.

Trong payment, mục tiêu thực dụng hơn nhiều là:

• không double-charge;
• không ghi ledger trùng;
• không mở entitlement hai lần;
• có thể replay an toàn;
• phát hiện và reconcile khi có lệch.

Chìa khóa số 1: chọn identity đúng cho việc deduplicate

Sai lầm phổ biến nhất là dedup theo toàn bộ payload hash hoặc theo order_id một cách đơn giản. Cả hai đều dễ sai.

Vì sao payload hash dễ vỡ

Payload có thể thay đổi không ảnh hưởng đến logical event:

• thêm field metadata;
• đổi thứ tự key JSON;
• provider thêm thông tin debug;
• replay từ nguồn khác có timestamp envelope khác.

Nếu dedup theo hash của raw payload, cùng logical event có thể trượt qua lớp chống duplicate.

Vì sao chỉ dedup theo order_id cũng sai

Một order có thể trải qua nhiều sự kiện hợp lệ:

• payment.authorized
• payment.captured
• payment.failed
• refund.created
• refund.succeeded

Nếu chỉ khóa bằng order_id, anh có thể vô tình nuốt mất event hợp lệ tiếp theo.

Identity tốt hơn là gì?

Thông thường nên ưu tiên theo thứ tự:

1. provider event id nếu gateway phát hành một event id ổn định và retry vẫn giữ nguyên;
2. payment provider transaction/reference id + event type nếu event id không đáng tin hoặc không tồn tại;
3. logical operation key do mình chuẩn hóa nội bộ nếu phải ingest từ nhiều nguồn.

Điều quan trọng là identity phải đại diện cho cùng một semantic effect, không chỉ giống hình thức payload.

Chìa khóa số 2: dedup store phải nằm trên đường side effect, không chỉ ở memory

Một Set trong process memory, Redis TTL đơn giản hoặc cache local của pod chỉ giải quyết được một phần rất nhỏ. Khi scale ngang hoặc restart service, duplicate vẫn lọt.

Một dedup store đủ tin được cho payment workloads nên có ít nhất:

• key dedup ổn định;
• write mang tính atomic hoặc được bảo vệ bằng unique constraint;
• trạng thái xử lý (processing, processed, failed, ignored);
• timestamp nhận event, source, raw reference;
• TTL hoặc retention policy hợp lý;
• khả năng tra cứu cho support/reconciliation.

Mẫu bảng thường dùng

create table inbound_event_dedup (
  dedup_key text primary key,
  provider text not null,
  event_type text not null,
  external_event_id text,
  payment_reference text,
  status text not null,
  first_seen_at timestamptz not null default now(),
  last_seen_at timestamptz not null default now(),
  processed_at timestamptz,
  error_code text,
  payload_checksum text,
  raw_payload jsonb
);

Ở đây dedup_key mới là trung tâm. Nếu insert bị conflict, consumer biết rằng event này đã được thấy trước đó.

Nhưng dừng ở đây vẫn chưa đủ.

Có dedup row rồi vẫn có thể double side effect nếu transaction boundary sai

Nhiều team làm như sau:

1. insert vào bảng dedup nếu chưa có;
2. commit;
3. chạy business logic và side effect tiếp theo;
4. cập nhật trạng thái processed sau cùng.

Lỗ hổng ở giữa rất lớn. Nếu service crash sau bước 2 nhưng trước bước 4, lần retry sau sẽ gặp row đã tồn tại. Nếu code hiểu “đã tồn tại nghĩa là xử lý xong”, side effect cần thiết bị bỏ lỡ. Nếu code hiểu “cứ làm lại”, side effect có thể lặp.

Vì vậy, dedup không chỉ là chuyện chống duplicate. Nó còn là chuyện biểu diễn vòng đời xử lý.

Mô hình an toàn hơn: inbox pattern cho webhook ingestion

Trong nhiều hệ thống payment, cách đáng tin hơn là tách làm hai pha:

Pha 1: ingest webhook vào inbox một cách bền vững

Webhook handler làm tối thiểu:

• verify signature;
• chuẩn hóa identity;
• upsert vào bảng inbound/inbox;
• trả ACK nhanh nếu dữ liệu đã được nhận bền vững.

Pha 2: worker nội bộ xử lý side effect từ inbox

Worker đọc inbox event và áp business transition, ledger update, email, entitlement, notification... theo cách idempotent hơn và có thể retry nội bộ.

Ưu điểm:

• webhook endpoint phản hồi nhanh hơn, ít timeout hơn;
• duplicate từ provider dừng ở inbox key;
• retry logic được chuyển vào nội bộ, dễ kiểm soát hơn;
• quan sát trạng thái từng event tốt hơn;
• replay có điểm bắt đầu rõ ràng.

Cách này rất giống inbox/outbox thinking: gateway → inbox bền vững → domain processing → outbox side effect khác.

State machine mới là tuyến phòng thủ thật sự cho payment domain

Idempotency key không thể thay thế state machine. Payment là domain có trạng thái nghiệp vụ rõ ràng. Nếu transition không được bảo vệ, duplicate event dễ tạo side effect lặp hoặc transition vô nghĩa.

Ví dụ một order chỉ nên cho phép:

• pending -> authorized
• authorized -> captured
• captured -> refunded hoặc partially_refunded
• pending -> failed

Nếu event payment.captured đến hai lần, transition thứ hai nên trở thành:

• no-op có log/audit; hoặc
• idempotent read-back kết quả cũ.

Không nên để transition thứ hai tạo ledger entry mới chỉ vì “event đến thì cứ xử lý”.

Một guard quan trọng

Business update nên encode expectation rõ ràng, ví dụ:

update payments
set status = 'captured', captured_at = now()
where payment_id = $1 and status = 'authorized';

Nếu row_count = 0, worker phải phân biệt:

• event duplicate hợp lệ vì payment đã captured rồi;
• event đến sai thứ tự;
• payment đang ở trạng thái bất thường cần điều tra.

Đây là lý do payment systems tốt luôn gắn idempotency với state transition, không tách rời.

Race condition khi nhiều worker cùng nhận một event

Ở production, duplicate không chỉ đến theo thời gian. Nó còn đến đồng thời.

Ví dụ:

• provider retry trong lúc request đầu chưa hoàn tất;
• load balancer chuyển hai request giống nhau vào hai pod khác nhau;
• queue consumer scale out và cùng thấy một thông điệp do cơ chế retry/rebalance.

Nếu logic là “check rồi mới insert”, race condition rất dễ làm lọt duplicate:

1. worker A query chưa thấy dedup key;
2. worker B query chưa thấy dedup key;
3. cả hai cùng thực hiện side effect;
4. ai insert sau thì mới biết mình thua — nhưng đã quá muộn.

Đúng hơn là dùng primitive atomic

Thường sẽ chọn một trong các cách sau:

• insert ... on conflict do nothing với unique key;
• transaction + row lock nếu cần khóa resource cụ thể;
• advisory lock cho một logical key trong scope ngắn;
• queue partitioning theo payment reference để giảm song song cùng key.

Điểm mấu chốt: quyền xử lý first-writer phải được quyết định atomically trước side effect không đảo ngược.

Ledger entries phải tự idempotent, đừng chỉ tin lớp webhook

Một anti-pattern rất hay gặp là tin rằng nếu webhook layer đã dedup thì downstream ledger có thể insert bình thường. Điều này nguy hiểm vì replay, manual script, batch backfill hoặc bug orchestration vẫn có thể gọi tới ledger layer trực tiếp.

Ledger write tốt nên có khóa uniqueness riêng cho business action, ví dụ:

• provider_event_id;
• hoặc payment_id + entry_type;
• hoặc payment_id + external_reference + semantic_action.

Nếu ledger là sổ cái tài chính hoặc balance movement, uniqueness ở đây là bắt buộc chứ không phải nice-to-have.

Nói cách khác: payment system tốt thường có nhiều lớp idempotency chồng nhau:

• API request layer;
• inbound webhook layer;
• domain state transition layer;
• ledger/accounting layer;
• outbound email/notification/fulfillment layer.

Out-of-order event còn nguy hiểm hơn duplicate thuần túy

Webhook idempotency thường được nhắc cùng duplicate, nhưng payment systems ngoài đời còn dính event đến không đúng thứ tự.

Ví dụ:

• payment.captured đến trước payment.authorized vì provider retry khác nhau;
• refund.succeeded đến trước event đồng bộ trạng thái capture do network path khác;
• reconciliation import một snapshot mới vào khi luồng realtime vẫn đang chậm.

Nếu backend chỉ chống duplicate mà không có state model, nó vẫn có thể sai.

Cách xử lý thực dụng

• encode allowed transitions;
• giữ raw event để có thể reprocess;
• đánh dấu event deferred nếu prerequisite chưa có;
• định kỳ retry hoặc drive bằng projection/state reconciliation;
• alert nếu một event bị defer quá lâu.

Trong payment, “idempotent” mà không “order-aware” vẫn chưa đủ.

Signature verification và idempotency là hai tuyến khác nhau

Có team verify chữ ký webhook rất tốt rồi chủ quan nghĩ vậy là an toàn. Không hẳn.

• Signature verification trả lời: event này đúng là do provider gửi không?
• Idempotency trả lời: nếu event thật này đến hai lần hoặc được replay hợp lệ thì side effect của mình có lặp không?

Cả hai đều bắt buộc. Thiếu một trong hai thì hệ thống vẫn yếu.

Observability: phải nhìn được duplicate rate, not just error rate

Nếu dashboard của anh chỉ nhìn 5xx, latency và throughput, anh sẽ bỏ sót rất nhiều lỗi payment.

Một payment webhook pipeline nên có ít nhất các metric sau:

• số webhook nhận theo provider và event type;
• tỷ lệ dedup hit;
• số event processing, processed, failed, deferred;
• số transition bị từ chối vì state không hợp lệ;
• số ledger uniqueness conflict;
• số manual replay và kết quả replay;
• age của oldest unprocessed inbox event.

Những alert hữu ích

• dedup hit rate tăng đột biến sau deploy hoặc sự cố mạng;
• số event payment.succeeded vào inbox tăng nhưng số payment chuyển captured/paid không tăng tương ứng;
• ledger conflict tăng đột biến;
• defer queue tích tụ lâu;
• một provider event type mới xuất hiện nhưng chưa có mapping logic.

Ở payment systems, nhiều bug nặng không lộ qua crash. Nó lộ qua mismatch giữa event flow và domain outcome.

Retention của dedup key nên dài bao lâu?

Không có con số chung cho mọi hệ thống. Nhưng chọn TTL quá ngắn là lỗi cực phổ biến.

TTL phải phản ánh thực tế vận hành:

• provider có thể retry trong bao lâu?
• operator có replay/backfill dữ liệu trong bao lâu?
• dispute/reconciliation có thể đưa event cũ quay lại không?
• audit/compliance có đòi truy vết lâu hơn không?

Với payment, giữ dedup record vài phút hoặc vài giờ thường là quá ngắn. Nhiều team chọn theo ngày hoặc lâu hơn, nhất là cho event có tác động tài chính trực tiếp.

Nếu lo kích thước dữ liệu, tách retention giữa:

• dedup identity tối giản giữ lâu hơn;
• raw payload đầy đủ giữ ngắn hơn hoặc lưu cold storage.

Reconciliation là lưới an toàn cuối cùng

Ngay cả khi hệ thống idempotent khá tốt, payment vẫn nên có reconciliation. Lý do là không phải mọi sự cố đều xuất hiện dưới dạng duplicate thuần túy.

Một job reconciliation tốt có thể so:

• payment gateway truth;
• trạng thái payment nội bộ;
• ledger/balance movement;
• order/subscription entitlement.

Ví dụ các mismatch cần phát hiện:

• gateway báo captured, nhưng payment nội bộ vẫn authorized;
• payment nội bộ paid, nhưng thiếu ledger entry;
• ledger có movement nhưng order chưa unlock entitlement;
• một event bị đánh dấu processed nhưng side effect downstream chưa xảy ra.

Idempotency giảm xác suất bug. Reconciliation giảm thời gian bug sống sót.

Một flow tham khảo đủ thực dụng cho production

1. Provider gửi webhook.
2. Webhook endpoint verify signature.
3. Chuẩn hóa provider, event_type, external_event_id, payment_reference.
4. Tạo dedup_key theo quy tắc đã thống nhất.
5. insert ... on conflict do nothing vào inbox/dedup table.
6. Nếu conflict:

- update last_seen_at và counter; - trả ACK an toàn; - không tái chạy side effect trực tiếp.

7. Nếu insert mới thành công:

- enqueue internal processing hoặc mark status received.

8. Worker đọc inbox event theo transaction boundary chặt chẽ.
9. Worker áp state transition có guard.
10. Worker ghi ledger bằng uniqueness key riêng.
11. Worker phát side effect phụ qua outbox nếu cần.
12. Mark inbox event processed khi các bước bắt buộc đã hoàn tất.
13. Reconciliation job định kỳ quét mismatch.

Điều đẹp nhất của flow này là replay cũng có đường đi rõ ràng: replay vào inbox rồi để worker domain xử lý lại dưới các guard cũ, thay vì bắn script ad-hoc thẳng vào business tables.

Khi nào nên trả 200 sớm, khi nào nên giữ connection đến lúc xử lý xong?

Với payment webhook, mình nghiêng mạnh về hướng ACK sau khi đã persist bền vững vào inbox, không đợi toàn bộ side effect hoàn tất.

Lý do:

• giảm timeout với provider;
• giảm retry không cần thiết;
• tách external delivery khỏi internal processing;
• dễ scale và quan sát hơn.

Tất nhiên, nếu persist thất bại thì phải trả lỗi để provider retry. Nhưng nếu đã ghi bền vững rồi, đừng giữ connection chỉ để email, ledger sync phụ hoặc entitlement hoàn tất trên cùng request path.

Những anti-pattern rất đáng tránh

1. Dùng raw payload hash làm khóa duy nhất cho mọi trường hợp

Dễ miss duplicate semantic tương đương nhưng payload khác envelope.

2. Dedup chỉ trong Redis với TTL vài phút

Restart, cross-region hoặc replay ngày hôm sau sẽ xuyên qua lớp này.

3. Xem “đã có row dedup” là “đã xử lý xong”

Nếu previous attempt chết giữa chừng, anh có thể mất side effect cần thiết.

4. Không encode state transition

Duplicate và out-of-order event sẽ làm domain trôi loạn.

5. Ledger không có uniqueness guard riêng

Một bug orchestration nhỏ có thể biến thành sai lệch tài chính thật.

6. Replay bằng script ad-hoc chạy thẳng business logic

Rất khó bảo đảm cùng guard, cùng logging và cùng idempotency assumptions như pipeline chính.

Internal links nên gắn trong cluster

• Nếu anh đang dùng tool hoặc workflow automation có side effect ra hệ khác, bài Tool Calling Reliability cho AI Agent hữu ích để thấy idempotency không chỉ là chuyện payment mà là chuyện mọi hệ thống gọi ra ngoài rồi retry.
• Với hệ event-driven giữa database và broker, bài Transactional Outbox trong Backend giúp nối thêm tư duy "ghi bền vững trước, phát side effect sau".
• Nếu cần nhìn duplicate/retry ở góc poison message và replay queue, bài Dead Letter Queue trong Event-Driven Systems là cặp đọc rất hợp.
• Để phân biệt lúc nào nên khóa tranh chấp bằng lock và lúc nào nên thiên về idempotent design, bài Distributed Locks trong Backend Production sẽ giúp tránh lạm dụng distributed lock cho mọi race condition.
• Nếu team đang truy lỗi sau một incident tài chính hoặc fulfillment, bài Incident Postmortem giúp chuẩn hóa cách ghi nhận chuỗi nguyên nhân và guardrail sau sự cố.

Kết luận

Trong payment systems, duplicate webhook không phải điều bất thường. Nó là mặc định phải chấp nhận. Vì vậy, câu hỏi đúng không phải là “làm sao để provider chỉ gửi một lần”, mà là “nếu provider gửi nhiều lần, replay lại hoặc giao sai thứ tự, hệ thống của mình còn đúng không?”.

Một thiết kế webhook idempotency đủ mạnh thường không nằm ở một trick đơn lẻ. Nó là tổ hợp của:

• identity dedup đúng semantic;
• inbox bền vững;
• transaction boundary chặt;
• state machine có guard;
• ledger uniqueness;
• observability theo duplicate/defer/conflict;
• reconciliation để vá phần đời thực không bao giờ sạch tuyệt đối.

Nếu phải rút gọn thành một nguyên tắc: đừng cố hứa exactly-once cho cả hệ thống; hãy làm side effect đủ idempotent để duplicate trở thành chuyện chịu được trong production.