commit 6faae9f3620d0bc54728259cf322c05b3adf099f
parent 4c9dd8ca58633e4f9d63a2d6d994dfd961558389
Author: bohdan-potuzhnyi <bohdan.potuzhnyi@gmail.com>
Date: Tue, 11 Nov 2025 17:19:54 +0100
#0010574
Diffstat:
3 files changed, 42 insertions(+), 7 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -357,7 +357,7 @@ remain absolutely unchanged.
// True if **all** challenges must be solved (AND), false if
// it is sufficient to solve one of them (OR).
- combi_and: bool;
+ combi_and: boolean;
}
@@ -1940,7 +1940,7 @@ Inspecting instances
// True if the ``email`` address was validated.
// @since **v21**.
- email_validated?: bool;
+ email_validated?: boolean;
// Merchant phone number for password reset (2-FA)
// @since **v21**.
@@ -1948,7 +1948,7 @@ Inspecting instances
// True if the ``email`` address was validated.
// @since **v21**.
- phone_validated?: bool;
+ phone_validated?: boolean;
// Merchant public website.
website?: string;
@@ -5019,6 +5019,33 @@ The webhook is a backend feature that is used to send a confirmation to the merc
customer paid the merchant. It will show the date and the price the customer paid. For details on setup and supported event payloads, see the
`Merchant manual – Setting up a webhook <https://docs.taler.net/taler-merchant-manual.html#setting-up-a-webhook>`_.
+Each webhook is bound to an ``event_type``. The backend currently recognizes the following types, which are mirrored in the ``WebhookEventType`` enum so API clients can
+validate their payloads without guesswork:
+
+.. ts:def:: WebhookEventType
+
+ enum WebhookEventType {
+ ORDER_CREATED = "order_created",
+ PAY = "pay",
+ REFUND = "refund",
+ ORDER_SETTLED = "order_settled",
+ CATEGORY_ADDED = "category_added",
+ CATEGORY_UPDATED = "category_updated",
+ CATEGORY_DELETED = "category_deleted",
+ INVENTORY_ADDED = "inventory_added",
+ INVENTORY_UPDATED = "inventory_updated",
+ INVENTORY_DELETED = "inventory_deleted"
+ }
+
+- ``order_created``: fired whenever a new order is created and exposes the ``order_id``, contract, and owning ``instance_id``.
+- ``pay``: emitted after a payment succeeds; the payload contains the paid contract terms and ``order_id``.
+- ``refund``: triggered when a refund is approved and includes timestamp, refunded amount, and reason.
+- ``order_settled``: sent when reconciliation links a wire transfer to an order (includes ``order_id`` and ``wtid``).
+- ``category_added`` / ``category_updated`` / ``category_deleted``: cover lifecycle changes to product categories.
+- ``inventory_added`` / ``inventory_updated`` / ``inventory_deleted``: cover lifecycle changes to inventory items, including descriptive fields and stock state.
+
+For the full payloads associated with each event consult the merchant manual section linked above.
+
Adding webhooks
@@ -5052,7 +5079,7 @@ Adding webhooks
webhook_id: string;
// The event of the webhook: why the webhook is used.
- event_type: string;
+ event_type: WebhookEventType;
// URL of the webhook where the customer will be redirected.
url: string;
@@ -5098,7 +5125,7 @@ Editing webhooks
interface WebhookPatchDetails {
// The event of the webhook: why the webhook is used.
- event_type: string;
+ event_type: WebhookEventType;
// URL of the webhook where the customer will be redirected.
url: string;
@@ -5154,7 +5181,7 @@ Inspecting webhook
webhook_id: string;
// The event of the webhook: why the webhook is used.
- event_type: string;
+ event_type: WebhookEventType;
}
@@ -5180,7 +5207,7 @@ Inspecting webhook
interface WebhookDetails {
// The event of the webhook: why the webhook is used.
- event_type: string;
+ event_type: WebhookEventType;
// URL of the webhook where the customer will be redirected.
url: string;
diff --git a/design-documents/073-extended-merchant-template.rst b/design-documents/073-extended-merchant-template.rst
@@ -208,6 +208,10 @@ by using ``TemplateWalletContractPayload``.
type TemplateWalletContractPayload =
TemplateWalletContractDetails | TemplateInventoryContractDetailsWallet;
+.. ts:def:: TemplateWalletContractDetails
+
+ type TemplateWalletContractDetails = TemplateContractDetails;
+
``TemplateWalletContractDetails`` is identical to the ``TemplateContractDetails``
object defined in :ref:`merchant-template-api`. Changes relative to the current
protocol are called out below.
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
@@ -1234,6 +1234,7 @@ Order created events
For "order_created" events, the backend will provide the following
information to the Mustache templating engine:
+* webhook_type: "order_created".
* order_id: the identifier of the newly created order.
* contract: the full JSON contract for the order (see :ref:`contract_terms <contract-terms>` for the structure).
* instance_id: the merchant instance identifier that created the order.
@@ -1245,6 +1246,7 @@ Order pay events
For "pay" events, the backend will provide the following
information to the Mustache templating engine:
+* webhook_type: "pay".
* :ref:`contract_terms <contract-terms>`: the contract terms of the paid order.
* order_id: the ID of the order that received the refund.
@@ -1256,6 +1258,7 @@ For "refund" events which are triggered when a refund is
approved, the backend will provide the following information to the
Mustache templating engine:
+* webhook_type: "refund".
* timestamp: time of the refund (using a `Timestamp` with the time in seconds since the UNIX epoch).
* order_id: the ID of the order that received the refund.
* :ref:`contract_terms <contract-terms>`: the full JSON of the contract terms of the refunded order.
@@ -1274,6 +1277,7 @@ an incoming wire transfer from the exchange to a paid
order, the backend will provide the following information to the limited
Mustache templating engine:
+* webhook_type: "order_settled".
* order_id: The unique identifier of the order that has been fully settled (all payments completed and wired to the merchant).
* wtid: The wire transfer ID of the settlement.
