feat(webhook): per-instruction beneficiary event payload

api-reference/fx-webhook/events/beneficiary/beneficiary-payment-instruction-approved.mdx

@@ -1,5 +1,5 @@
 ---
 title: "BENEFICIARY_PAYMENT_INSTRUCTION_APPROVED"
-description: "Fires when a payment instruction on a beneficiary is approved; check instructions[].status to find the one that transitioned."
+description: "Fires when a payment instruction on a beneficiary is approved. Carries the affected instruction plus beneficiary context."
 openapi: "apis/fx-webhook/openapi.yml webhook BENEFICIARY_PAYMENT_INSTRUCTION_APPROVED"
 ---

api-reference/fx-webhook/events/beneficiary/beneficiary-payment-instruction-rejected.mdx

@@ -1,5 +1,5 @@
 ---
 title: "BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED"
-description: "Fires when a payment instruction on a beneficiary is rejected; check instructions[].status to find the one that transitioned."
+description: "Fires when a payment instruction on a beneficiary is rejected. Carries the affected instruction plus beneficiary context."
 openapi: "apis/fx-webhook/openapi.yml webhook BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED"
 ---

apis/fx-webhook/openapi.yml

@@ -1014,33 +1014,38 @@ components:
         - customerId
         - assets
         - atTime
-    BeneficiaryEvent:
+    BeneficiaryPaymentInstructionEvent:
       type: object
       description: >
         Payload delivered for beneficiary payment-instruction lifecycle events
         (`BENEFICIARY_PAYMENT_INSTRUCTION_CREATED`, `BENEFICIARY_PAYMENT_INSTRUCTION_APPROVED`,
         `BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED`).
 
-        Review status is tracked **per payment instruction**, not on the
-        beneficiary itself. The payload always carries the full beneficiary
-        snapshot — to find which instruction triggered the event, inspect
-        `instructions[].status` (or, for `created`, the most recently added
-        entry).
+        Each event corresponds to **one** payment instruction transition. The
+        payload includes the affected `instruction` plus enough beneficiary
+        context (`id`, `customerId`, `holder`, `relationshipType`) to act on
+        the event without an extra lookup. To see the full set of payment
+        instructions attached to a beneficiary, call
+        `GET /api/beneficiaries/{beneficiaryId}` on the fx-payment API.
       properties:
         id:
           type: string
           format: uuid
+          description: ID of the beneficiary the affected instruction belongs to.
           readOnly: true
         customerId:
           type: string
           format: uuid
         holder:
           $ref: "#/components/schemas/HolderEvent"
-        instructions:
-          type: array
-          description: Payment instructions attached to the beneficiary, each with its own review status.
-          items:
-            $ref: "#/components/schemas/PaymentInstructionEvent"
+        relationshipType:
+          type: string
+          enum:
+            - SELF_OWNED
+            - THIRD_PARTY
+          description: Whether the beneficiary is the customer themselves (`SELF_OWNED`) or a separate party (`THIRD_PARTY`).
+        instruction:
+          $ref: "#/components/schemas/PaymentInstructionEvent"
         atTime:
           type: string
           format: date-time
@@ -1049,7 +1054,8 @@ components:
         - id
         - customerId
         - holder
-        - instructions
+        - relationshipType
+        - instruction
         - atTime
     OperationEvent:
       type: object
@@ -1454,16 +1460,16 @@ webhooks:
         the beneficiary itself is first created and when an additional
         instruction is later attached. The new instruction enters
         `PENDING_REVIEW` and transitions independently to `APPROVED` or
-        `REJECTED`. The payload is the full beneficiary snapshot; inspect
-        `instructions[]` to find the newly added one.
+        `REJECTED`. The payload carries the affected `instruction` plus the
+        beneficiary context (`id`, `customerId`, `holder`, `relationshipType`).
       tags:
         - Beneficiary
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/BeneficiaryEvent"
+              $ref: "#/components/schemas/BeneficiaryPaymentInstructionEvent"
       responses:
         "200":
           $ref: "#/components/responses/WebhookAck"
@@ -1472,18 +1478,17 @@ webhooks:
       summary: Beneficiary payment instruction approved
       description: >
         Fires when one of the beneficiary's payment instructions is approved
-        and becomes usable. Review status lives on each instruction; check
-        `instructions[].status` to find the one that just transitioned. A
-        beneficiary with multiple instructions emits this event once per
-        approval.
+        and becomes usable. The payload carries the approved `instruction`
+        (with `status: APPROVED`) plus the beneficiary context. A beneficiary
+        with multiple instructions emits this event once per approval.
       tags:
         - Beneficiary
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/BeneficiaryEvent"
+              $ref: "#/components/schemas/BeneficiaryPaymentInstructionEvent"
       responses:
         "200":
           $ref: "#/components/responses/WebhookAck"
@@ -1492,18 +1497,18 @@ webhooks:
       summary: Beneficiary payment instruction rejected
       description: >
         Fires when one of the beneficiary's payment instructions is rejected
-        in compliance review and cannot be used. Review status lives on each
-        instruction; check `instructions[].status` to find the one that just
-        transitioned. A beneficiary with multiple instructions emits this
-        event once per rejection.
+        in compliance review and cannot be used. The payload carries the
+        rejected `instruction` (with `status: REJECTED`) plus the beneficiary
+        context. A beneficiary with multiple instructions emits this event
+        once per rejection.
       tags:
         - Beneficiary
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/BeneficiaryEvent"
+              $ref: "#/components/schemas/BeneficiaryPaymentInstructionEvent"
       responses:
         "200":
           $ref: "#/components/responses/WebhookAck"