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

[MrAdder]

Refs #4550

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.

[Copilot]

Pull request overview

Refactors the VATSIM.net webhook processing pipeline to make action handling deterministic (timestamp ordering + chained dispatch), improve observability, and reduce duplicated delta parsing logic across webhook jobs.

Changes:

• Refactored ProcessVatsimNetWebhook to sort actions deterministically, resolve jobs via a map, and dispatch via Bus::chain() with structured logging.
• Introduced InteractsWithMemberDeltas trait and updated MemberCreatedAction / MemberChangedAction to use cached delta parsing helpers.
• Added a feature test asserting unknown webhook actions return 400 Bad Request.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
app/Http/Controllers/External/VatsimNet/ProcessVatsimNetWebhook.php	Centralizes action→job resolution, sorts actions by timestamp, chains jobs, and improves logging/empty-payload handling.
app/Jobs/ExternalServices/VatsimNet/Webhooks/Concerns/InteractsWithMemberDeltas.php	Adds reusable cached delta parsing + changed-field map helpers.
app/Jobs/ExternalServices/VatsimNet/Webhooks/MemberCreatedAction.php	Simplifies creation handling using the delta trait and adds debug logging.
app/Jobs/ExternalServices/VatsimNet/Webhooks/MemberChangedAction.php	Refactors update handling into focused methods using the delta trait and adds debug logging.
tests/Feature/External/Webhooks/WebhooksTest.php	Adds coverage for unknown webhook action returning 400.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.