Understand Every Line of
WebhookFlow

com.campustoai.webhook/ ├── model/ ← JPA Entities — Java classes that become DB tables │ ├── WebhookEvent.java → table: webhook_events │ ├── WebhookSubscription.java → table: subscriptions │ ├── DeliveryLog.java → table: delivery_logs │ ├── EventSource.java → table: event_sources │ └── EventStatus.java → enum (not a table) │ ├── repository/ ← Spring Data JPA interfaces — auto-generated SQL │ ├── WebhookEventRepository.java │ ├── WebhookSubscriptionRepository.java │ ├── DeliveryLogRepository.java │ └── EventSourceRepository.java │ ├── service/ ← Business logic — the "brain" of the application │ ├── WebhookEventService.java → orchestrates receive flow │ ├── EventDeliveryService.java → HTTP delivery + retry │ ├── SubscriptionService.java → subscription CRUD + matching │ ├── EventSourceService.java → source CRUD │ ├── HmacValidationService.java → signature security │ └── AnalyticsService.java → metrics aggregation │ ├── controller/ ← REST Controllers — HTTP in, HTTP out │ ├── EventController.java │ ├── SubscriptionController.java │ ├── SourceController.java │ └── AnalyticsController.java │ ├── dto/ ← Data Transfer Objects — what we send/receive over HTTP │ ├── EventResponse.java → safe view of WebhookEvent │ ├── CreateSubscriptionRequest.java → validated input for POST /subscriptions │ └── ... │ └── exception/ ← Centralized error handling ├── GlobalExceptionHandler.java └── ResourceNotFoundException.java, ...

@Entity // → Hibernate creates: CREATE TABLE webhook_events (...) @Table(name = "webhook_events", indexes = { @Index(columnList = "source"), // → CREATE INDEX ... ON webhook_events(source) @Index(columnList = "status") // → CREATE INDEX ... ON webhook_events(status) }) public class WebhookEvent { @Id // PRIMARY KEY @GeneratedValue(strategy = GenerationType.IDENTITY) // AUTO_INCREMENT private Long id; @Column(nullable = false) // NOT NULL constraint in DB private String source; // "razorpay", "github" @Column(unique = true) // UNIQUE constraint — for idempotency private String externalId; @Lob // Store as TEXT, not VARCHAR(255) @Column(columnDefinition = "TEXT") // Explicit type for H2 + PostgreSQL private String payload; @Enumerated(EnumType.STRING) // Stores "RECEIVED" not 0 — safe to add new values later private EventStatus status; @OneToMany(mappedBy = "event", // DeliveryLog.event is the owner of the relationship cascade = CascadeType.ALL, // Delete event → auto-delete all its delivery logs fetch = FetchType.LAZY) // Don't load logs from DB unless explicitly needed private List<DeliveryLog> deliveryLogs; @PrePersist // Runs before INSERT — auto-sets timestamps protected void onCreate() { if (receivedAt == null) receivedAt = LocalDateTime.now(); } }

// LAZY (default for @OneToMany) — CORRECT ✅ @OneToMany(fetch = FetchType.LAZY) private List<DeliveryLog> deliveryLogs; // deliveryLogs is NOT loaded from DB when you load the WebhookEvent // Only loaded when you call event.getDeliveryLogs() — saves DB round trips // EAGER — DANGEROUS ❌ (don't do this for lists) @OneToMany(fetch = FetchType.EAGER) // Every time you load ANY WebhookEvent, ALL delivery logs are also loaded // Load 100 events → 100 extra queries for delivery logs → N+1 problem

public interface WebhookEventRepository extends JpaRepository<WebhookEvent, Long> { // Spring generates: SELECT * FROM webhook_events WHERE external_id = ? // Optional means it might return null — caller must handle both cases Optional<WebhookEvent> findByExternalId(String externalId); // SELECT * FROM webhook_events ORDER BY received_at DESC List<WebhookEvent> findAllByOrderByReceivedAtDesc(); // SELECT * FROM webhook_events WHERE source = ? ORDER BY received_at DESC List<WebhookEvent> findBySourceOrderByReceivedAtDesc(String source); // SELECT * FROM webhook_events WHERE status = ? ORDER BY received_at DESC List<WebhookEvent> findByStatusOrderByReceivedAtDesc(EventStatus status); // SELECT * FROM webhook_events WHERE source = ? AND status = ? ORDER BY ... List<WebhookEvent> findBySourceAndStatusOrderByReceivedAtDesc(String source, EventStatus status); // SELECT * FROM webhook_events WHERE received_at > ? ORDER BY ... // "After" keyword maps to the > operator in SQL List<WebhookEvent> findByReceivedAtAfterOrderByReceivedAtDesc(LocalDateTime from); // SELECT COUNT(*) FROM webhook_events WHERE received_at > ? long countByReceivedAtAfter(LocalDateTime since); }

// ❌ Field injection — works but bad practice @Autowired private WebhookEventRepository repository; // Problems: can't unit test without Spring, dependencies are hidden, allows null fields // ✅ Constructor injection — the correct way private final WebhookEventRepository repository; // final = cannot be reassigned after construction public WebhookEventService(WebhookEventRepository repository) { this.repository = repository; // Spring calls this constructor and passes the dependency } // Benefits: explicit dependencies, testable without Spring, object always fully initialized

public WebhookEvent receive(String sourceName, String rawPayload, String signatureHeader, String eventType, String externalId) { // STEP 1 — Verify source exists (throws 404 if not registered) EventSource source = eventSourceService.getByName(sourceName); // STEP 2 — Validate HMAC signature (throws 401 if tampered) hmacValidationService.validate(rawPayload, signatureHeader, source.getSecretKey(), sourceName); // STEP 3 — Idempotency check (return 200 if already processed) if (externalId != null && repository.findByExternalId(externalId).isPresent()) { throw new DuplicateEventException(externalId); } // STEP 4 — Build and save the entity WebhookEvent event = new WebhookEvent(); event.setSource(sourceName); event.setEventType(eventType != null ? eventType : "unknown"); event.setPayload(rawPayload); WebhookEvent saved = repository.save(event); // INSERT — id is auto-assigned here // STEP 5 — Deliver to matching subscribers deliveryService.deliver(saved); return saved; // Controller gets the saved event and returns eventId to the sender }

// findById returns Optional<WebhookEvent> — might be empty if id doesn't exist Optional<WebhookEvent> result = repository.findById(id); // Bad way — might throw NullPointerException ❌ WebhookEvent event = result.get(); // Crashes if empty! // Good way — throw a meaningful 404 error ✅ WebhookEvent event = result .orElseThrow(() -> new ResourceNotFoundException("Event not found: " + id)); // orElseThrow: if value is present → return it; if empty → throw the given exception

public String computeHmac(String payload, String secretKey) { // Mac = Message Authentication Code class from Java's crypto library Mac mac = Mac.getInstance("HmacSHA256"); // Wrap the secret key string in a SecretKeySpec so Mac can use it SecretKeySpec keySpec = new SecretKeySpec( secretKey.getBytes(StandardCharsets.UTF_8), // Key as bytes "HmacSHA256" ); mac.init(keySpec); // Initialize with the key byte[] hash = mac.doFinal( // Compute HMAC of the payload payload.getBytes(StandardCharsets.UTF_8) ); return HexFormat.of().formatHex(hash); // Convert bytes [10,255] → "0aff" }

// Wait times between retry attempts private static final int[] RETRY_DELAYS_SECONDS = {0, 1, 5, 30}; // ↑ ↑ ↑ ↑ // attempt1 2 3 4 // attempt 1 (index 0): 0s — no wait, try immediately // attempt 2 (index 1): 1s — wait 1 second before retry // attempt 3 (index 2): 5s — wait 5 seconds // attempt 4 (index 3): 30s — wait 30 seconds // After 4 failures → return false → event marked FAILED

// RestTemplate is Spring's HTTP client for calling other services HttpHeaders headers = new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); // Content-Type: application/json headers.set("X-WebhookFlow-Event", event.getEventType()); // Custom headers so subscriber knows what arrived // Bundle the payload + headers into one object HttpEntity<String> request = new HttpEntity<>(event.getPayload(), headers); // Make the HTTP POST call — returns status code + response body ResponseEntity<String> response = restTemplate.postForEntity( sub.getTargetUrl(), // e.g. https://orders.myapp.com/webhook request, // body + headers String.class // parse response body as a String ); boolean success = response.getStatusCode().is2xxSuccessful(); // 200–299 = success

// After EVERY attempt (success or failure), we save a DeliveryLog row DeliveryLog log = new DeliveryLog(); log.setEvent(event); // Foreign key: event_id log.setSubscription(sub); // Foreign key: subscription_id log.setAttemptNumber(attempt); // 1, 2, 3, or 4 log.setResponseStatus(statusCode); // 200, 500, or 0 (timeout) log.setSuccess(success); log.setDurationMs(durationMs); // How long the call took — for latency analytics deliveryLogRepository.save(log); // Why? Full observability — you can answer: // "Event 42 failed to deliver to Order Service — what happened?" // → Check delivery_logs WHERE event_id = 42 → see all 4 attempts, status codes, errors

@RestController // = @Controller + @ResponseBody (auto-serialize to JSON) @RequestMapping("/api/events") // All methods in this class start with /api/events public class EventController { @PostMapping("/receive/{source}") // Maps POST /api/events/receive/razorpay public ResponseEntity<ReceiveEventResponse> receive( @PathVariable String source, // URL: /receive/razorpay → source = "razorpay" @RequestBody String rawPayload, // HTTP body → raw JSON string @RequestHeader(value = "X-Signature", // Read this HTTP header required = false) String signature, // null if not sent @RequestHeader(value = "X-Event-Type", required = false) String eventType, @RequestHeader(value = "X-External-Id", required = false) String externalId ) { WebhookEvent event = eventService.receive(source, rawPayload, signature, eventType, externalId); return ResponseEntity.ok( // ResponseEntity.ok() = 200 OK status new ReceiveEventResponse(event.getId(), "RECEIVED", "Event accepted") ); } @GetMapping // Maps GET /api/events public ResponseEntity<List<EventResponse>> listEvents( @RequestParam(required = false) String source, // ?source=razorpay (optional) @RequestParam(required = false) String status, // ?status=FAILED (optional) @RequestParam(required = false) @DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME) LocalDateTime from // ?from=2025-01-01T00:00:00 ) { return ResponseEntity.ok(eventService.findAll(source, status, from)); } }

@RestControllerAdvice // Intercepts exceptions from ALL @RestController classes public class GlobalExceptionHandler { @ExceptionHandler(ResourceNotFoundException.class) public ResponseEntity<...> handleNotFound(ResourceNotFoundException ex) { return errorResponse(HttpStatus.NOT_FOUND, ex.getMessage()); // → 404 } @ExceptionHandler(DuplicateEventException.class) public ResponseEntity<...> handleDuplicate(DuplicateEventException ex) { // Duplicates return 200 — Razorpay retries on any non-2xx! ← crucial design decision return ResponseEntity.ok(body); } @ExceptionHandler(MethodArgumentNotValidException.class) public ResponseEntity<...> handleValidation(MethodArgumentNotValidException ex) { // Collect field errors: { "targetUrl": "must be a valid URL", "name": "required" } Map<String, String> fieldErrors = new HashMap<>(); for (FieldError err : ex.getBindingResult().getFieldErrors()) { fieldErrors.put(err.getField(), err.getDefaultMessage()); } return ResponseEntity.badRequest().body(body); // → 400 } @ExceptionHandler(Exception.class) // Catches ANYTHING not caught above public ResponseEntity<...> handleGeneral(Exception ex) { return errorResponse(HttpStatus.INTERNAL_SERVER_ERROR, "An unexpected error occurred"); // We don't expose ex.getMessage() — might leak internal details to the client } }