feat(webhooks): include app_instance_uuid in app instance webhook payloads

[pmelab]

Problem

The app_instance.created and app_instance.status_changed webhook payloads identify the instance only by app_instance_id — Polydock's internal auto-increment id.

Consumers never see that id. The API returns uuid when an instance is created, and uuid is the route key for the instance endpoints (getRouteKeyName() returns 'uuid'). A receiver holding a uuid therefore has no way to resolve an incoming webhook back to the instance it provisioned, short of an extra API round trip per delivery — and there is no endpoint to look an instance up by internal id anyway.

This blocks MOAD, which correlates inbound Polydock webhooks to the outbound create call by uuid.

Change

• CreateWebhookCallForAppInstanceStatusChanged adds app_instance_uuid to the payload, alongside the existing app_instance_id.
• New tests/Feature/Listeners/CreateWebhookCallForAppInstanceStatusChangedTest.php pins the identifying payload fields for both event types.
• docs/WEBHOOKS.md gains an "App instance events" section documenting the payload shape and stating that app_instance_uuid is the identifier to key on. Sensitive-data wording matches the actual getWebhookSafeData() behaviour: sensitive keys are always redacted, the flag only re-adds the generated app-admin credentials.
• New migration backfills uuids for rows created before the nullable uuid column existed (2025-03-21), so app_instance_uuid is never null in a payload.

Purely additive: no existing field is renamed, removed, or changed, so current consumers are unaffected.

Testing

vendor/bin/pint --test, phpstan analyse and the full php artisan test suite (577 passed) run clean locally. Also verified against the incoming QA-tooling ratchet (#256): its rector config and PHPStan max+strict analysis are clean on these files, so merging both branches in either order won't trip the new CI gates.

🤖 Generated with Claude Code

Greptile Summary

The PR adds the public app-instance UUID to instance webhook payloads and documents the updated contract.

• Backfills UUIDs for legacy rows while preserving existing UUIDs.
• Uses one atomic update on supported production databases to avoid an inter-chunk null-UUID window.
• Adds feature coverage for both webhook event types and migration behavior.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
app/Listeners/CreateWebhookCallForAppInstanceStatusChanged.php	Adds the API-visible UUID to both app-instance webhook payload variants without changing existing fields.
database/migrations/2026_08_06_000001_backfill_uuid_on_polydock_app_instances_table.php	Backfills only null UUIDs and uses an atomic update for the repository's supported production database drivers.
docs/WEBHOOKS.md	Documents the app-instance event payload and accurately scopes sensitive-data handling.
tests/Feature/Listeners/CreateWebhookCallForAppInstanceStatusChangedTest.php	Pins UUID and status fields for created and status-changed webhook events.
tests/Feature/Migrations/BackfillUuidOnPolydockAppInstancesTest.php	Verifies that legacy null UUIDs are populated while existing UUIDs remain unchanged.

Sequence Diagram

sequenceDiagram
    participant Migration
    participant DB as App Instance Database
    participant Model as App Instance
    participant Listener as Webhook Listener
    participant Receiver as Webhook Consumer
    Migration->>DB: Backfill legacy null UUIDs
    Model->>Listener: Created or status-changed event
    Listener->>DB: Store webhook call with ID and UUID
    Listener-->>Receiver: Queued signed delivery
    Receiver->>Receiver: Correlate using app_instance_uuid

Loading

_{Reviews (3): Last reviewed commit: "fix(webhooks): close inter-chunk null-uu..." | Re-trigger Greptile}

Context used (3)

• Knowledge Base — Models and Persistence
• Knowledge Base — API and outbound webhooks
• Knowledge Base — Trial Registration Flow