feat(backend): add incoming payment created webhook event

localenv/mock-account-servicing-entity/app/lib/webhooks.server.ts

@@ -6,6 +6,7 @@ import { apolloClient } from './apolloClient'
 import { v4 as uuid } from 'uuid'
 
 export enum EventType {
+  IncomingPaymentCreated = 'incoming_payment.created',
   IncomingPaymentCompleted = 'incoming_payment.completed',
   IncomingPaymentExpired = 'incoming_payment.expired',
   OutgoingPaymentCreated = 'outgoing_payment.created',

packages/backend/src/open_payments/payment/incoming/model.ts

@@ -18,6 +18,7 @@ import {
 } from '@interledger/open-payments'
 
 export enum IncomingPaymentEventType {
+  IncomingPaymentCreated = 'incoming_payment.created',
   IncomingPaymentExpired = 'incoming_payment.expired',
   IncomingPaymentCompleted = 'incoming_payment.completed'
 }

packages/backend/src/open_payments/payment/incoming/service.test.ts

@@ -73,6 +73,11 @@ describe('Incoming Payment Service', (): void => {
       ${undefined}                                  | ${false}       | ${undefined}                     | ${undefined}               | ${undefined}
       ${faker.internet.url({ appendSlash: false })} | ${true}        | ${new Date(Date.now() + 30_000)} | ${'Test incoming payment'} | ${'#123'}
     `('An incoming payment can be created', async (options): Promise<void> => {
+      await expect(
+        IncomingPaymentEvent.query(knex).where({
+          type: IncomingPaymentEventType.IncomingPaymentCreated
+        })
+      ).resolves.toHaveLength(0)
       const incomingPayment = await incomingPaymentService.create({
         paymentPointerId,
         ...options,
@@ -84,6 +89,11 @@ describe('Incoming Payment Service', (): void => {
         asset,
         processAt: new Date(incomingPayment.expiresAt.getTime())
       })
+      await expect(
+        IncomingPaymentEvent.query(knex).where({
+          type: IncomingPaymentEventType.IncomingPaymentCreated
+        })
+      ).resolves.toHaveLength(1)
     })
 
     test('Cannot create incoming payment for nonexistent payment pointer', async (): Promise<void> => {

packages/backend/src/open_payments/payment/incoming/service.ts

@@ -141,6 +141,11 @@ async function createIncomingPayment(
     })
     .withGraphFetched('[asset, paymentPointer]')
 
+  await IncomingPaymentEvent.query(trx || deps.knex).insert({
+    type: IncomingPaymentEventType.IncomingPaymentCreated,
+    data: incomingPayment.toData(BigInt(0))
+  })
+
   return await addReceivedAmount(deps, incomingPayment, BigInt(0))
 }
 
@@ -234,7 +239,7 @@ async function handleDeactivated(
         : IncomingPaymentEventType.IncomingPaymentCompleted
     deps.logger.trace({ type }, 'creating incoming payment webhook event')
 
-    await IncomingPaymentEvent.query(deps.knex).insertAndFetch({
+    await IncomingPaymentEvent.query(deps.knex).insert({
       type,
       data: incomingPayment.toData(amountReceived),
       withdrawal: {

packages/backend/src/open_payments/payment/outgoing/lifecycle.ts

@@ -182,7 +182,7 @@ export const sendWebhookEvent = async (
         amount: balance
       }
     : undefined
-  await PaymentEvent.query(deps.knex).insertAndFetch({
+  await PaymentEvent.query(deps.knex).insert({
     type,
     data: payment.toData({ amountSent, balance }),
     withdrawal

packages/backend/src/openapi/webhooks.yaml

@@ -87,6 +87,7 @@ components:
         type:
           type: string
           enum:
+            - incoming_payment.created
             - incoming_payment.completed
             - incoming_payment.expired
         data:

packages/documentation/docs/integration/getting-started.md

@@ -80,6 +80,7 @@ The endpoint accepts a `POST` request with
 
 | Value                              | Description                                                                 |
 | ---------------------------------- | --------------------------------------------------------------------------- |
+| `incoming_payment.created`         | Incoming payment has been created.                                          |
 | `incoming_payment.completed`       | Incoming payment is complete and doesn't accept any incoming funds anymore. |
 | `incoming_payment.expired`         | Incoming payment is expired and doesn't accept any incoming funds anymore.  |
 | `outgoing_payment.created`         | Outgoing payment was created.                                               |
@@ -91,6 +92,12 @@ The `backend` package requires an environment variable called `WEBHOOK_URL` whic
 
 ### Event Handlers
 
+#### `incoming_payment.created`
+
+An [Open Payments](./glossary#open-payments) Incoming Payment was created. This is for information purposes only and does not require an action.
+
+- Action: None
+
 #### `incoming_payment.completed`
 
 An [Open Payments](../reference/glossary.md#open-payments) Incoming Payment was completed, either manually or programmatically, i.e. it does not accept any incoming funds anymore. The Account Servicing Entity SHOULD withdraw all funds received and deposit them into the payee's account.