🔄 Refactor: VATSIM.net Webhook Processing (Improved Observability & Safety)

[MrAdder]

This PR further refactors the VATSIM.net webhook pipeline to improve determinism, performance, logging, and internal structure while preserving existing behaviour.

---

🚀 Controller Improvements (ProcessVatsimNetWebhook)

✅ Deterministic Ordering

• Actions are sorted via collect()->sortBy('timestamp')->values() to guarantee correct execution order.
• Jobs are dispatched using Bus::chain() to prevent race conditions between actions.

🗺️ Centralised Action Resolution

• Introduced ACTION_JOB_MAP constant to replace the switch statement.
• Added createActionJob() resolver method.
• Unknown actions now:
  • Log structured error context
  • Return 400 Bad Request

This makes the system easier to extend with additional webhook actions.

📊 Improved Logging & Observability

• Added structured logging:
  • resource
  • actions.length
  • actions.types
• Logs when:
  • Webhook received
  • No actions present (warning)
  • Jobs successfully chained
• Added preparation timing (preparation_ms) for lightweight performance insight.

🧯 Graceful Empty Payload Handling

• If no actions are present:
  • Logs a warning
  • Returns 200 OK
  • Avoids unnecessary queue dispatching

🔐 Security

• validateAuth() now strictly typed (: void)
• Shared-secret validation remains enforced

---

🧩 New Trait: InteractsWithMemberDeltas

Introduced reusable delta handling logic:

App\Jobs\ExternalServices\VatsimNet\Webhooks\Concerns\InteractsWithMemberDeltas

Features

• Cached delta collection
• Cached changed field map
• getDeltaAfter(field) helper
• changedFields() keyed map of field => after

This removes duplicated delta parsing logic and reduces repeated collection operations.

---

👤 MemberChangedAction Refactor

Structural Changes

• Uses InteractsWithMemberDeltas trait
• Added ACCOUNT_FIELDS constant
• Extracted focused processing methods:
  • processAccountChanges()
  • processRatingChanges()
  • processStateChange()

Behaviour Improvements

• Only updates scalar account fields if values actually changed.
• Ratings updated only when present in deltas.
• Region/Division updates preserve existing values if one side is omitted.
• Added debug log including changed field keys.

Benefits

• Fewer unnecessary DB writes
• Cleaner separation of concerns
• Reduced cognitive complexity
• Better observability

---

👶 MemberCreatedAction Refactor

• Uses shared delta trait
• Removed manual field collection helpers
• Simplified updateOrCreate logic
• Added structured debug logging with resource and account_id

Improves readability and consistency with the update handler.

---

🧪 Test Coverage Improvements

Added:

• test_unknown_action_returns_bad_request() to ensure invalid webhook actions return 400.

Existing tests validate:

• Correct chained execution order
• Proper handling of creation and update flows
• Behavioural parity after refactor

---

🧼 Overall Outcome

This refactor delivers:

• Deterministic processing order
• Cleaner and extensible action resolution
• Cached delta parsing for efficiency
• Reduced duplication across job handlers
• Safer handling of malformed payloads
• Improved structured logging and observability
• Stronger test coverage

The webhook pipeline is now more maintainable, extensible, and production-observable while preserving existing functionality.

[MrAdder]

^ The Failing check is a Github issue not myself

[MrAdder]

@AxonC or @kristiankunc I have tested this as best as possible however I do not have Webhook permissions with VatsimDev if one of you could test this that would be great.