feat(031): configurable webhooks — frontend UI + full test coverage (#4234)

Co-authored-by: ildyria <627094+ildyria@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: ildyria <beviguier@gmail.com>

Author: Copilot

app/Actions/Photo/Delete.php

@@ -9,12 +9,17 @@
 namespace App\Actions\Photo;
 
 use App\Actions\Shop\PurchasableService;
+use App\Assets\Features;
 use App\Constants\PhotoAlbum as PA;
 use App\DTO\Delete\PhotosToBeDeletedDTO;
+use App\Enum\SizeVariantType;
 use App\Events\PhotoDeleted;
+use App\Events\PhotoWillBeDeleted;
 use App\Exceptions\Internal\LycheeLogicException;
 use App\Exceptions\ModelDBException;
+use App\Models\SizeVariant;
 use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Storage;
 
 /**
  * Deletes the photos with the designated IDs **efficiently**.
@@ -108,6 +113,13 @@ public function do(array $photo_ids, string|null $from_id): void
 
 		$this->purchasable_service->deleteMulitplePhotoPurchasables($photo_ids, [$from_id]);
 
+		// Fire PhotoWillBeDeleted for each photo that will be hard-deleted,
+		// BEFORE executeDelete() removes the records from the database.
+		// Load a lean snapshot of photo data (id, title) and their size variants.
+		if (count($delete_photo_ids) > 0) {
+			$this->dispatchWillBeDeletedEvents($delete_photo_ids, $from_id);
+		}
+
 		$photos_to_be_deleted = new PhotosToBeDeletedDTO(
 			force_delete_photo_ids: $delete_photo_ids,
 			soft_delete_photo_ids: $photo_ids,
@@ -122,4 +134,56 @@ public function do(array $photo_ids, string|null $from_id): void
 			dispatch($job);
 		}
 	}
+
+	/**
+	 * Fire PhotoWillBeDeleted for each photo scheduled for hard deletion.
+	 *
+	 * Uses a lean DB query (no full Eloquent hydration) to load photo title
+	 * and size variant URLs before the records are removed.
+	 *
+	 * @param string[] $photo_ids IDs of photos to be hard-deleted
+	 * @param string   $album_id  the album they are being deleted from
+	 */
+	private function dispatchWillBeDeletedEvents(array $photo_ids, string $album_id): void
+	{
+		// Skip this
+		if (Features::inactive('webhook')) {
+			return;
+		}
+
+		// Load minimal photo data.
+		$photos_data = DB::table('photos')
+			->whereIn('id', $photo_ids)
+			->select(['id', 'title'])
+			->get();
+
+		$photos_data->chunk(500)->each(function ($chunk) use ($album_id): void {
+			$photo_ids_chunked = $chunk->pluck('id')->all();
+			// Load size variant data for all photos in one query.
+			$size_variants = SizeVariant::whereIn('photo_id', $photo_ids_chunked)
+				->select(['photo_id', 'type', 'short_path', 'storage_disk'])
+				->get()
+				->groupBy('photo_id');
+
+			foreach ($chunk as $photo) {
+				$variants = [];
+				$raw_variants = $size_variants->get($photo->id, collect());
+				/** @var SizeVariant $sv */
+				foreach ($raw_variants as $sv) {
+					$url = $sv->type === SizeVariantType::PLACEHOLDER ? $sv->short_path : $sv->getDownloadUrlAttribute();
+					$variants[] = [
+						'type' => $sv->type->name(),
+						'url' => $url,
+					];
+				}
+
+				PhotoWillBeDeleted::dispatch(
+					$photo->id,
+					$album_id,
+					$photo->title,
+					$variants,
+				);
+			}
+		});
+	}
 }

app/Actions/Photo/MoveOrDuplicate.php

@@ -14,6 +14,7 @@
 use App\Contracts\Models\AbstractAlbum;
 use App\Events\AlbumSaved;
 use App\Events\PhotoDeleted;
+use App\Events\PhotoMoved;
 use App\Models\Album;
 use App\Models\Photo;
 use App\Models\Purchasable;
@@ -83,6 +84,13 @@ public function do(Collection $photos, ?AbstractAlbum $from_album, ?Album $to_al
 			foreach ($photos as $photo) {
 				$this->applyToPurchasable($photo->id, $from_album->get_id(), $to_album?->get_id());
 			}
+
+			// Dispatch PhotoMoved for each moved photo (cross-album move only; not duplication).
+			if ($to_album !== null) {
+				foreach ($photos as $photo) {
+					PhotoMoved::dispatch($photo->id, $from_album->get_id(), $to_album->id);
+				}
+			}
 		}
 
 		$notify = new Notify();

app/Actions/Photo/Pipes/Shared/SetParent.php

@@ -12,6 +12,7 @@
 use App\Contracts\PhotoCreate\SharedPipe;
 use App\DTO\PhotoCreate\DuplicateDTO;
 use App\DTO\PhotoCreate\StandaloneDTO;
+use App\Events\PhotoAdded;
 use App\Events\PhotoSaved;
 use App\Exceptions\Internal\LycheeLogicException;
 use App\Models\Album;
@@ -49,6 +50,12 @@ public function handle(DuplicateDTO|StandaloneDTO $state, \Closure $next): Dupli
 			// Dispatch event for album stats recomputation
 			// This must be done after SetParent so the photo_album relationship exists
 			PhotoSaved::dispatch($state->photo->id);
+
+			// Dispatch PhotoAdded for new photo records only (upload, import, duplication).
+			// Existing records that were re-saved into a different album are handled by PhotoMoved.
+			if ($state->photo->wasRecentlyCreated) {
+				PhotoAdded::dispatch($state->photo->id);
+			}
 		}
 
 		return $next($state);

app/Console/Commands/WebhookTest.php

@@ -0,0 +1,75 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Console\Commands;
+
+use App\Assets\Features;
+use App\DTO\WebhookPayload;
+use App\Jobs\WebhookDispatchJob;
+use App\Models\Webhook;
+use Illuminate\Console\Command;
+
+/**
+ * Artisan command to test a webhook configuration by sending a synthetic HTTP request.
+ *
+ * Usage: php artisan lychee:webhook-test <id>
+ *
+ * Fires the job synchronously so the operator can immediately see the result.
+ */
+class WebhookTest extends Command
+{
+	protected $signature = 'lychee:webhook-test {id : The ULID of the webhook to test}';
+
+	protected $description = 'Send a test HTTP request to a configured webhook endpoint.';
+
+	public function handle(): int
+	{
+		if (Features::inactive('webhook')) {
+			$this->warn('The webhook feature is disabled (WEBHOOK_ENABLED is not set to true).');
+			$this->warn('Set WEBHOOK_ENABLED=true in your .env file and clear the config cache to enable it.');
+
+			return self::FAILURE;
+		}
+
+		$id = $this->argument('id');
+
+		/** @var Webhook|null $webhook */
+		$webhook = Webhook::find($id);
+
+		if ($webhook === null) {
+			$this->error("Webhook not found: {$id}");
+
+			return self::FAILURE;
+		}
+
+		$this->info("Testing webhook: {$webhook->name} ({$webhook->url})");
+
+		// Build a synthetic payload with clearly labelled test data.
+		$payload = new WebhookPayload(
+			photo_id: 'TEST_PHOTO_ID',
+			album_id: 'TEST_ALBUM_ID',
+			title: 'Test Photo (lychee:webhook-test)',
+			size_variants: [
+				['type' => 'original', 'url' => 'https://example.com/test-original.jpg'],
+				['type' => 'thumb', 'url' => 'https://example.com/test-thumb.jpg'],
+			],
+		);
+
+		// Dispatch synchronously so the operator sees the outcome immediately.
+		try {
+			(new WebhookDispatchJob($webhook, $payload))->handle();
+			$this->info('Webhook test dispatched. Check storage/logs/laravel.log for the result.');
+		} catch (\Throwable $e) {
+			$this->error('Webhook dispatch failed: ' . $e->getMessage());
+
+			return self::FAILURE;
+		}
+
+		return self::SUCCESS;
+	}
+}

app/DTO/WebhookPayload.php

@@ -0,0 +1,90 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\DTO;
+
+/**
+ * Data transfer object representing the payload to be sent to a webhook endpoint.
+ *
+ * Fields are nullable; a null value means the field was not selected for inclusion.
+ */
+final class WebhookPayload
+{
+	/**
+	 * @param string|null                                   $photo_id      the photo ID (null if not selected)
+	 * @param string|null                                   $album_id      the album ID (null if not selected)
+	 * @param string|null                                   $title         the photo title (null if not selected)
+	 * @param array<int,array{type:string,url:string}>|null $size_variants array of {type, url} objects (null if not selected)
+	 */
+	public function __construct(
+		public readonly ?string $photo_id,
+		public readonly ?string $album_id,
+		public readonly ?string $title,
+		public readonly ?array $size_variants,
+	) {
+	}
+
+	/**
+	 * Return the payload as a flat associative array for JSON encoding.
+	 * Only non-null fields are included.
+	 *
+	 * @return array<string, mixed>
+	 */
+	public function toJsonArray(): array
+	{
+		$payload = [];
+
+		if ($this->photo_id !== null) {
+			$payload['photo_id'] = $this->photo_id;
+		}
+		if ($this->album_id !== null) {
+			$payload['album_id'] = $this->album_id;
+		}
+		if ($this->title !== null) {
+			$payload['title'] = $this->title;
+		}
+		if ($this->size_variants !== null) {
+			$payload['size_variants'] = $this->size_variants;
+		}
+
+		return $payload;
+	}
+
+	/**
+	 * Return the payload as a flat associative array for query-string encoding.
+	 *
+	 * Scalar fields (photo_id, album_id, title) are passed as-is.
+	 * Size variant URLs are base64-encoded (standard base64) and keyed as
+	 * `size_variant_{type}` — e.g. `size_variant_original`, `size_variant_medium`.
+	 * This avoids URL-encoding ambiguity for S3/CDN URLs.
+	 *
+	 * @return array<string, string>
+	 */
+	public function toQueryArray(): array
+	{
+		$payload = [];
+
+		if ($this->photo_id !== null) {
+			$payload['photo_id'] = $this->photo_id;
+		}
+		if ($this->album_id !== null) {
+			$payload['album_id'] = $this->album_id;
+		}
+		if ($this->title !== null) {
+			$payload['title'] = $this->title;
+		}
+		if ($this->size_variants !== null) {
+			foreach ($this->size_variants as $variant) {
+				$key = 'size_variant_' . $variant['type'];
+				$payload[$key] = base64_encode($variant['url']);
+			}
+		}
+
+		return $payload;
+	}
+}

app/Enum/PhotoWebhookEvent.php

@@ -0,0 +1,25 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Enum;
+
+use App\Enum\Traits\DecorateBackedEnum;
+
+/**
+ * Enum PhotoWebhookEvent.
+ *
+ * The lifecycle events for which a webhook can be triggered.
+ */
+enum PhotoWebhookEvent: string
+{
+	use DecorateBackedEnum;
+
+	case ADD = 'photo.add';
+	case MOVE = 'photo.move';
+	case DELETE = 'photo.delete';
+}

app/Enum/WebhookMethod.php

@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Enum;
+
+use App\Enum\Traits\DecorateBackedEnum;
+
+/**
+ * Enum WebhookMethod.
+ *
+ * The HTTP methods allowed for outgoing webhook requests.
+ */
+enum WebhookMethod: string
+{
+	use DecorateBackedEnum;
+
+	case GET = 'GET';
+	case POST = 'POST';
+	case PUT = 'PUT';
+	case PATCH = 'PATCH';
+	case DELETE = 'DELETE';
+}

app/Enum/WebhookPayloadFormat.php

@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2017-2018 Tobias Reich
+ * Copyright (c) 2018-2026 LycheeOrg.
+ */
+
+namespace App\Enum;
+
+use App\Enum\Traits\DecorateBackedEnum;
+
+/**
+ * Enum WebhookPayloadFormat.
+ *
+ * Determines how the webhook payload is delivered in outgoing HTTP requests.
+ */
+enum WebhookPayloadFormat: string
+{
+	use DecorateBackedEnum;
+
+	/** Payload is sent as a JSON request body with Content-Type: application/json. */
+	case JSON = 'json';
+
+	/** Payload is sent as URL query parameters appended to the webhook URL. */
+	case QUERY_STRING = 'query_string';
+}