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

app/Listeners/CreateWebhookCallForAppInstanceStatusChanged.php

@@ -39,6 +39,10 @@ public function handle(PolydockAppInstanceStatusChanged|PolydockAppInstanceCreat
                 'event' => $previousStatus === null ? 'app_instance.created' : 'app_instance.status_changed',
                 'payload' => [
                     'app_instance_id' => $event->appInstance->id,
+                    // The uuid is the instance's public identifier — it is what the
+                    // API returns on create and what consumers hold on to, so the
+                    // webhook has to carry it for them to resolve the instance.
+                    'app_instance_uuid' => $event->appInstance->uuid,
                     'store_id' => $event->appInstance->storeApp->store->id,
                     'store_name' => $event->appInstance->storeApp->store->name,
                     'store_app_id' => $event->appInstance->polydock_store_app_id,

database/migrations/2026_08_06_000001_backfill_uuid_on_polydock_app_instances_table.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Str;
+
+return new class extends Migration
+{
+    /**
+     * The uuid column was added nullable (2025_03_21) without backfilling rows
+     * that already existed, so their status transitions would emit webhook
+     * payloads with a null app_instance_uuid — the field consumers are told to
+     * key on. Assign uuids to those legacy rows, including soft-deleted ones.
+     */
+    public function up(): void
+    {
+        if (in_array(DB::connection()->getDriverName(), ['mysql', 'mariadb'], true)) {
+            // Single atomic statement: no window between chunks where a
+            // concurrent status transition could still read a null uuid.
+            DB::statement('UPDATE polydock_app_instances SET uuid = UUID() WHERE uuid IS NULL');
+
+            return;
+        }
+
+        // Portable fallback for drivers without UUID() (sqlite in tests, where
+        // there is no concurrent traffic to race against).
+        DB::table('polydock_app_instances')
+            ->whereNull('uuid')
+            ->orderBy('id')
+            ->chunkById(100, function ($instances): void {
+                foreach ($instances as $instance) {
+                    DB::table('polydock_app_instances')
+                        ->where('id', $instance->id)
+                        ->update(['uuid' => Str::uuid()->toString()]);
+                }
+            });
+    }
+
+    public function down(): void
+    {
+        // Intentionally a no-op: backfilled uuids are indistinguishable from
+        // boot-assigned ones, and consumers may already hold them.
+    }
+};

docs/WEBHOOKS.md

@@ -18,6 +18,36 @@ Each delivery is an HTTP `POST` with a JSON body and the following headers:
 | `X-Polydock-Attempt` | The current delivery attempt number |
 | `X-Polydock-Signature` | `sha256=<hex>` HMAC of the raw request body |
 
+## App instance events
+
+`app_instance.created` and `app_instance.status_changed` share one payload
+shape. The two events differ only in `previous_status`, which is `null` for
+`app_instance.created`:
+
+```json
+{
+    "app_instance_id": 42,
+    "app_instance_uuid": "0f1c9a3e-6d2b-4e1a-9b6f-2c4d8e7a5b31",
+    "store_id": 1,
+    "store_name": "Example store",
+    "store_app_id": 7,
+    "store_app_name": "Example app",
+    "previous_status": "pending-deploy",
+    "current_status": "deploy-completed",
+    "data": {},
+    "timestamp": "2026-01-01T12:00:00+00:00"
+}
+```
+
+Identify the instance by `app_instance_uuid` — it is the instance's public
+identifier, the value returned by the API when the instance is created and the
+key used in instance API routes. `app_instance_id` is Polydock's internal
+auto-increment id and is not stable across environments.
+
+`data` holds the instance's provisioning data. Sensitive keys are always
+redacted; setting `include_sensitive_data` additionally includes the generated
+app-admin username and password.
+
 ## Verifying the signature
 
 The `X-Polydock-Signature` header lets you confirm a request genuinely came

tests/Feature/Listeners/CreateWebhookCallForAppInstanceStatusChangedTest.php

@@ -0,0 +1,106 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Feature\Listeners;
+
+use App\Events\PolydockAppInstanceCreatedWithNewStatus;
+use App\Events\PolydockAppInstanceStatusChanged;
+use App\Listeners\CreateWebhookCallForAppInstanceStatusChanged;
+use App\Models\PolydockAppInstance;
+use App\Models\PolydockStore;
+use App\Models\PolydockStoreApp;
+use App\Models\PolydockStoreWebhook;
+use App\Models\PolydockStoreWebhookCall;
+use App\Polydock\Core\Enums\PolydockAppInstanceStatus;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\Queue;
+use Illuminate\Support\Str;
+use Tests\TestCase;
+
+/**
+ * The app-instance webhook payload is a published contract: consumers hold the
+ * instance `uuid` (it is what the API returns on create and the only identifier
+ * they ever see), so a payload without it cannot be resolved back to an
+ * instance. The identifying fields are pinned here.
+ */
+class CreateWebhookCallForAppInstanceStatusChangedTest extends TestCase
+{
+    use RefreshDatabase;
+
+    private function makeInstance(PolydockAppInstanceStatus $status): PolydockAppInstance
+    {
+        $store = PolydockStore::factory()->create();
+        $storeApp = PolydockStoreApp::factory()->create([
+            'polydock_store_id' => $store->id,
+        ]);
+
+        PolydockStoreWebhook::factory()->active()->create([
+            'polydock_store_id' => $store->id,
+            'url' => 'https://example.com/webhooks/polydock',
+        ]);
+
+        $instance = new PolydockAppInstance;
+        $instance->polydock_store_app_id = $storeApp->id;
+        $instance->name = 'webhook-payload-test-'.Str::random(6);
+        $instance->app_type = 'test-app';
+        $instance->status = $status;
+        $instance->data = [];
+        // saveQuietly() skips the model's creating hook, which is what normally
+        // fills the uuid — set it explicitly so this test exercises the payload
+        // rather than the model's boot sequence.
+        $instance->uuid = (string) Str::uuid();
+        $instance->saveQuietly();
+
+        return $instance;
+    }
+
+    public function test_created_event_payload_carries_the_app_instance_uuid(): void
+    {
+        Queue::fake();
+
+        $instance = $this->makeInstance(PolydockAppInstanceStatus::NEW);
+
+        (new CreateWebhookCallForAppInstanceStatusChanged)->handle(
+            new PolydockAppInstanceCreatedWithNewStatus($instance),
+        );
+
+        $call = PolydockStoreWebhookCall::query()->sole();
+
+        self::assertSame('app_instance.created', $call->event);
+        self::assertSame($instance->uuid, $call->payload['app_instance_uuid']);
+        self::assertSame($instance->id, $call->payload['app_instance_id']);
+        self::assertNull($call->payload['previous_status']);
+        self::assertSame(
+            PolydockAppInstanceStatus::NEW->value,
+            $call->payload['current_status'],
+        );
+    }
+
+    public function test_status_changed_event_payload_carries_the_app_instance_uuid(): void
+    {
+        Queue::fake();
+
+        $instance = $this->makeInstance(PolydockAppInstanceStatus::PENDING_DEPLOY);
+
+        (new CreateWebhookCallForAppInstanceStatusChanged)->handle(
+            new PolydockAppInstanceStatusChanged(
+                $instance,
+                PolydockAppInstanceStatus::PENDING_PRE_DEPLOY,
+            ),
+        );
+
+        $call = PolydockStoreWebhookCall::query()->sole();
+
+        self::assertSame('app_instance.status_changed', $call->event);
+        self::assertSame($instance->uuid, $call->payload['app_instance_uuid']);
+        self::assertSame(
+            PolydockAppInstanceStatus::PENDING_PRE_DEPLOY->value,
+            $call->payload['previous_status'],
+        );
+        self::assertSame(
+            PolydockAppInstanceStatus::PENDING_DEPLOY->value,
+            $call->payload['current_status'],
+        );
+    }
+}

tests/Feature/Migrations/BackfillUuidOnPolydockAppInstancesTest.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Feature\Migrations;
+
+use App\Models\PolydockStore;
+use App\Models\PolydockStoreApp;
+use App\Polydock\Core\Enums\PolydockAppInstanceStatus;
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Str;
+use Tests\TestCase;
+
+class BackfillUuidOnPolydockAppInstancesTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_backfill_assigns_uuids_to_legacy_null_rows_only(): void
+    {
+        $store = PolydockStore::factory()->create();
+        $storeApp = PolydockStoreApp::factory()->create([
+            'polydock_store_id' => $store->id,
+        ]);
+
+        // Insert directly so no model boot hook fills the uuid, mirroring rows
+        // created before the uuid column existed.
+        $legacyId = DB::table('polydock_app_instances')->insertGetId([
+            'polydock_store_app_id' => $storeApp->id,
+            'name' => 'legacy-null-uuid',
+            'app_type' => 'test-app',
+            'status' => PolydockAppInstanceStatus::NEW->value,
+            'uuid' => null,
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+
+        $existingUuid = '0f1c9a3e-6d2b-4e1a-9b6f-2c4d8e7a5b31';
+        $modernId = DB::table('polydock_app_instances')->insertGetId([
+            'polydock_store_app_id' => $storeApp->id,
+            'name' => 'modern-with-uuid',
+            'app_type' => 'test-app',
+            'status' => PolydockAppInstanceStatus::NEW->value,
+            'uuid' => $existingUuid,
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+
+        $migration = require database_path('migrations/2026_08_06_000001_backfill_uuid_on_polydock_app_instances_table.php');
+        self::assertInstanceOf(Migration::class, $migration);
+        if (! method_exists($migration, 'up')) {
+            self::fail('Backfill migration does not define up()');
+        }
+        $migration->up();
+
+        $legacyUuid = DB::table('polydock_app_instances')->where('id', $legacyId)->value('uuid');
+        self::assertNotNull($legacyUuid);
+        self::assertTrue(Str::isUuid($legacyUuid));
+
+        // Rows that already had a uuid keep it untouched.
+        self::assertSame(
+            $existingUuid,
+            DB::table('polydock_app_instances')->where('id', $modernId)->value('uuid'),
+        );
+    }
+}