Webhook ProcessingWebhook Processing

webhook vào lúc cao điểminbound webhooks at peak

~300/s

webhook vào lúc cao điểminbound webhooks at peak

thời gian trả 2xx cho providertime to answer the provider with 2xx

< 100 ms

thời gian trả 2xx cho providertime to answer the provider with 2xx

cửa sổ chống replay theo timestampreplay window on the timestamp

5 phút

cửa sổ chống replay theo timestampreplay window on the timestamp

Stripe thử gửi lại nếu không nhận 2xxStripe keeps retrying without a 2xx

3 ngày

Stripe thử gửi lại nếu không nhận 2xxStripe keeps retrying without a 2xx

Bên trái là chiều vào: receiver chỉ kiểm chữ ký, đẩy vào Kafka và trả 200; processor làm việc thật, chống trùng và kiểm trạng thái. Bên phải là chiều ra: dispatcher ký payload, gửi tới khách hàng, thử lại có backoff và chuyển vào DLQ. Bật “Chữ ký giả” và “Provider gửi lại” để xem hai lớp bảo vệ.The left side is inbound: the receiver only checks the signature, queues to Kafka and answers 200; the processor does the real work, deduplicates and checks state. The right side is outbound: the dispatcher signs the payload, sends it to customers, retries with backoff and parks failures in a DLQ. Turn on “Forged signature” and “Provider retries” to see both safeguards.

1. 1

   Ai cũng gọi được endpoint webhookAnyone can call the webhook URL

   Kiểm HMAC-SHA256 trên raw body đúng từng byte, trước khi parse JSON; framework parse rồi serialize lại sẽ làm chữ ký sai. So sánh bằng MessageDigest.isEqual hoặc hmac.Equal để không lộ thời gian. Giữ hai secret khi xoay khoá.Verify HMAC-SHA256 over the exact raw bytes before parsing JSON; a framework that parses and re-serialises breaks the signature. Compare with MessageDigest.isEqual or hmac.Equal to avoid timing leaks. Keep two secrets valid while rotating.

   Chain of Responsibility
2. 2

   Replay một webhook thậtReplaying a genuine webhook

   Timestamp nằm trong phần được ký, receiver từ chối nếu lệch quá 5 phút. Dedup theo event id chặn nốt các bản replay trong cửa sổ đó.The timestamp is part of the signed string and the receiver rejects anything more than 5 minutes off. Dedup by event id stops replays inside that window.

   Chain of Responsibility
3. 3

   Xử lý lâu làm provider timeoutSlow handlers make the provider time out

   Stripe chờ khoảng 10 giây; quá thời gian là coi như lỗi và gửi lại, tạo thêm tải. Receiver chỉ kiểm chữ ký, ghi Kafka rồi trả 2xx; worker xử lý bất đồng bộ.Stripe waits about 10 seconds; anything slower counts as a failure and is resent, adding load. The receiver only checks the signature, writes to Kafka and answers 2xx; workers do the rest asynchronously.

   Producer-Consumer
4. 4

   Cùng sự kiện đến nhiều lầnThe same event arrives many times

   Provider giao at-least-once. Bảng processed_event có khoá chính (provider, event_id), chèn trong cùng transaction với cập nhật nghiệp vụ; 0 dòng nghĩa là bỏ qua.Providers deliver at least once. processed_event has a primary key of (provider, event_id) and is inserted in the same transaction as the business update; zero rows means skip.

   Retry with Exponential Backoff
5. 5

   Sự kiện đến sai thứ tựEvents arrive out of order

   charge.refunded có thể đến trước payment_intent.succeeded. Lưu last_event_at hoặc version trên payment, chỉ cho chuyển trạng thái tiến lên; khi nghi ngờ thì gọi GET /v1/payment_intents/{id} để lấy trạng thái thật thay vì tin payload.charge.refunded can arrive before payment_intent.succeeded. Store last_event_at or a version on the payment and allow only forward transitions; when unsure, call GET /v1/payment_intents/{id} for the real state instead of trusting the payload.

   State
6. 6

   Mỗi provider một định dạngEvery provider has its own format

   Stripe ký bằng header Stripe-Signature, VNPay ký vnp_SecureHash bằng HMAC-SHA512 trên query string, MoMo ký trường signature. Mỗi provider có một adapter kiểm chữ ký và chuyển về PaymentEvent nội bộ.Stripe signs with the Stripe-Signature header, VNPay signs vnp_SecureHash with HMAC-SHA512 over the query string, MoMo signs a signature field. One adapter per provider verifies and maps to an internal PaymentEvent.

   AdapterStrategy
7. 7

   Gửi webhook ra cho khách hàngSending webhooks to customers

   Ký payload bằng secret riêng của từng endpoint, kèm timestamp và event id. Thử lại với exponential backoff + jitter (1 phút, 5 phút, 30 phút… tới 24 giờ), quá 8 lần thì vào DLQ; endpoint lỗi liên tục 3 ngày thì tắt và email cho khách.Sign the payload with each endpoint's own secret and include a timestamp and event id. Retry with exponential backoff and jitter (1 min, 5 min, 30 min… up to 24 h), park it in the DLQ after 8 attempts, and disable an endpoint that has failed for 3 days and email the customer.

   Retry with Exponential BackoffCircuit Breaker

Receiver kiểm timestamp và HMAC, đẩy raw body vào Kafka rồi trả 200. Processor chống trùng bằng một lệnh INSERT … ON CONFLICT trong cùng transaction với cập nhật thanh toán.The receiver checks the timestamp and the HMAC, queues the raw body to Kafka and answers 200. The processor deduplicates with one INSERT … ON CONFLICT in the same transaction as the payment update.

@RestController
@RequiredArgsConstructor
public class StripeWebhook {
    private final KafkaTemplate<String, String> kafka;
    private final JdbcTemplate jdbc;
    private final PaymentService payments;
    @Value("${stripe.webhook-secret}") private String secret;

    @PostMapping("/webhooks/stripe")
    public ResponseEntity<Void> receive(@RequestBody String body,1
            @RequestHeader("Stripe-Signature") String header) throws Exception {
        Map<String, String> sig = Signatures.parse(header);     // t=…,v1=…
        long t = Long.parseLong(sig.get("t"));
        if (Math.abs(Instant.now().getEpochSecond() - t) > 300)
            return ResponseEntity.status(401).build();          // replay window
        byte[] expected = Signatures.hmacSha256(secret, t + "." + body);
        byte[] given = HexFormat.of().parseHex(sig.get("v1"));
        if (!MessageDigest.isEqual(expected, given))2
            return ResponseEntity.status(401).build();
        String key = Signatures.objectId(body);                 // pi_… keeps per-payment order
        kafka.send("webhook.inbound", key, body).get(2, TimeUnit.SECONDS);3
        return ResponseEntity.ok().build();                     // ~20 ms
    }

    @KafkaListener(topics = "webhook.inbound")
    @Transactional
    public void process(String body) {
        StripeEvent e = StripeEvent.parse(body);
        int fresh = jdbc.update("""4
            INSERT INTO processed_event(provider, event_id, event_type)
            VALUES ('stripe', ?, ?) ON CONFLICT DO NOTHING""", e.id(), e.type());
        if (fresh == 0) return;                                 // provider retry
        payments.apply(e.objectId(), e.type(), e.created());    // forward-only transition
    }
}

type Receiver struct {
	secret []byte
	writer *kafka.Writer
}

func (r *Receiver) ServeHTTP(w http.ResponseWriter, req *http.Request) {
	body, err := io.ReadAll(http.MaxBytesReader(w, req.Body, 1<<20))1
	if err != nil {
		http.Error(w, "body too large", http.StatusRequestEntityTooLarge)
		return
	}
	t, v1, ok := parseSignature(req.Header.Get("Stripe-Signature"))
	if !ok || abs(time.Now().Unix()-t) > 300 {
		http.Error(w, "missing or stale signature", http.StatusUnauthorized)
		return
	}
	mac := hmac.New(sha256.New, r.secret)
	fmt.Fprintf(mac, "%d.%s", t, body)
	if !hmac.Equal(mac.Sum(nil), v1) {2
		http.Error(w, "bad signature", http.StatusUnauthorized)
		return
	}
	ctx, cancel := context.WithTimeout(req.Context(), 2*time.Second)
	defer cancel()
	msg := kafka.Message{Key: []byte(objectID(body)), Value: body}
	if err := r.writer.WriteMessages(ctx, msg); err != nil {
		http.Error(w, "try again", http.StatusServiceUnavailable) // provider retries3
		return
	}
	w.WriteHeader(http.StatusOK)
}

func (p *Processor) Handle(ctx context.Context, e Event) error {
	return p.tx.Do(ctx, func(tx pgx.Tx) error {
		tag, err := tx.Exec(ctx, `INSERT INTO processed_event(provider, event_id, event_type)
			VALUES ('stripe', $1, $2) ON CONFLICT DO NOTHING`, e.ID, e.Type)
		if err != nil || tag.RowsAffected() == 0 {4
			return err // nil: duplicate delivery, skip
		}
		return applyPayment(ctx, tx, e) // locks the row, checks e.Created
	})
}

Mỗi pattern mở bài học tương ứng trong menu Pattern.Each one opens its lesson in the Patterns menu.