FOLIO: Post to a webhook after submitting a request

config/vufind/Folio.ini

@@ -212,6 +212,12 @@ available[] = "Open - Awaiting pickup"
 in_transit[] = "Open - In transit"
 in_transit[] = "Open - Awaiting delivery"
 
+; POST to this webhook address (with no body) after a successful hold is placed.
+; A web service hosted there may be used for follow-up actions.
+; Example: generating an email to circulation staff
+; (https://github.com/lehigh-university-libraries/folio-email-new-requests)
+;webhook = https://some.url/some-webhook-path
+
 [Holdings]
 ; This setting controls the sort order used when retrieving items from FOLIO for the
 ; holdings display; it should be a space-separated prioritized list of item record

module/VuFind/config/module.config.php

@@ -458,6 +458,7 @@
             'VuFind\Connection\ExternalVuFind' => 'VuFind\Connection\ExternalVuFindFactory',
             'VuFind\Connection\LibGuides' => 'VuFind\Connection\LibGuidesFactory',
             'VuFind\Connection\Relais' => 'VuFind\Connection\RelaisFactory',
+            'VuFind\Connection\Webhook' => 'Laminas\ServiceManager\Factory\InvokableFactory',
             'VuFind\Content\PageLocator' => 'VuFind\Content\PageLocatorFactory',
             'VuFind\Content\PluginManager' => 'VuFind\ServiceManager\AbstractPluginManagerFactory',
             'VuFind\Content\AuthorNotes\PluginManager' => 'VuFind\ServiceManager\AbstractPluginManagerFactory',

module/VuFind/src/VuFind/Connection/Webhook.php

@@ -0,0 +1,75 @@
+<?php
+
+/**
+ * Webhook connection class.
+ *
+ * PHP version 8
+ *
+ * Copyright (C) Villanova University 2023.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2,
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, see
+ * <https://www.gnu.org/licenses/>.
+ *
+ * @category VuFind
+ * @package  Connection
+ * @author   Maccabee Levine <msl321@lehigh.edu>
+ * @license  http://opensource.org/licenses/gpl-2.0.php GNU General Public License
+ * @link     https://vufind.org
+ */
+
+namespace VuFind\Connection;
+
+use Psr\Log\LoggerAwareInterface;
+
+/**
+ * Webhook connection class.
+ *
+ * @category VuFind
+ * @package  Connection
+ * @author   Maccabee Levine <msl321@lehigh.edu>
+ * @license  http://opensource.org/licenses/gpl-2.0.php GNU General Public License
+ * @link     https://vufind.org
+ */
+class Webhook implements
+    \VuFindHttp\HttpServiceAwareInterface,
+    LoggerAwareInterface
+{
+    use \VuFindHttp\HttpServiceAwareTrait;
+    use \VuFind\Log\LoggerAwareTrait {
+        logError as error;
+    }
+
+    /**
+     * Send a webhook post to the given URL. Log but do not throw any errors.
+     *
+     * @param string $url     Target URL (required for proper proxy setup for non-local addresses)
+     * @param ?float $timeout Request timeout in seconds (overrides configuration)
+     *
+     * @return void
+     */
+    public function post(string $url, ?float $timeout = null): void
+    {
+        $client = $this->httpService->createClient($url, 'POST', $timeout);
+
+        try {
+            $response = $client->send();
+            if (!$response->isSuccess()) {
+                $this->logError(
+                    "Failed to post to webhook. Code: {$response->getStatusCode()}, body: {$response->getBody()}"
+                );
+            }
+        } catch (\Exception $e) {
+            $this->logError('Failed to post webhook. Unexpected ' . $e::class . ': ' . (string)$e);
+        }
+    }
+}

module/VuFind/src/VuFind/ILS/Driver/Folio.php

@@ -34,6 +34,7 @@
 use Exception;
 use Laminas\Http\Response;
 use VuFind\Config\Feature\SecretTrait;
+use VuFind\Connection\Webhook;
 use VuFind\Exception\ILS as ILSException;
 use VuFind\I18n\Translator\TranslatorAwareInterface;
 use VuFind\ILS\Logic\AvailabilityStatus;
@@ -147,13 +148,15 @@ class Folio extends AbstractAPI implements
     /**
      * Constructor.
      *
-     * @param \VuFind\Date\Converter $dateConverter  Date converter object
-     * @param callable               $sessionFactory Factory function returning
-     * SessionContainer object
+     * @param \VuFind\Date\Converter $dateConverter     Date converter object
+     * @param callable               $sessionFactory    Factory function returning
+     *                                                  SessionContainer object
+     * @param Webhook                $webhookConnection Connection for webhooks
      */
     public function __construct(
         \VuFind\Date\Converter $dateConverter,
-        $sessionFactory
+        $sessionFactory,
+        protected Webhook $webhookConnection
     ) {
         $this->dateConverter = $dateConverter;
         $this->sessionFactory = $sessionFactory;
@@ -2365,6 +2368,21 @@ protected function performHoldRequest(array $requestBody): array
         ];
     }
 
+    /**
+     * Support method for placeHold(): Notify an external process
+     * that a request was successfully submitted.
+     *
+     * @return void
+     */
+    protected function sendWebhookAfterHoldRequest()
+    {
+        $url = $this->config['Holds']['webhook'] ?? null;
+        if ($url && $this->webhookConnection) {
+            // Short timeout -- don't impact user.
+            $this->webhookConnection->post($url, 5);
+        }
+    }
+
     /**
      * Get allowed service points for a request. Returns null if data cannot be obtained.
      *
@@ -2499,6 +2517,7 @@ public function placeHold($holdDetails)
             $requestBody['requestType'] = $requestType;
             $result = $this->performHoldRequest($requestBody);
             if ($result['success']) {
+                $this->sendWebhookAfterHoldRequest();
                 break;
             }
         }

module/VuFind/src/VuFind/ILS/Driver/FolioFactory.php

@@ -71,6 +71,7 @@ public function __invoke(
             $manager = $container->get(\Laminas\Session\SessionManager::class);
             return new \Laminas\Session\Container("Folio_$namespace", $manager);
         };
-        return parent::__invoke($container, $requestedName, [$sessionFactory]);
+        $webhookConnection = $container->get(\VuFind\Connection\Webhook::class);
+        return parent::__invoke($container, $requestedName, [$sessionFactory, $webhookConnection]);
     }
 }