Xendit webhook: metadata.app routing + survival audit log + rolling fallback file

Every Xendit invoice now carries metadata: { app: 'halobestie_v2' } so an
external webhook router (no DB access) can fan out v1/v2 traffic purely off
the echoed payload.

Every inbound webhook lands in a new webhook_logs table BEFORE auth or
business logic, so a forensic row survives 401/409/unknown/exception paths.
Primary fields are parsed as columns; raw_body keeps the full payload
verbatim. The handler captures outcome in closure-scoped vars and stamps
http_status/processing_result/processing_error in a single update before
the lone reply.send() — Fastify flushes reply.send() immediately, which
defeated the original finally-block stamp.

A non-UUID external_id no longer crashes the Postgres cast; it ACKs with
ignored_non_uuid_external_id so Xendit stops retrying legacy old-app IDs.

When the DB log itself fails, an optional rolling JSONL file sink absorbs
the event. Disabled by default — opt in via XENDIT_WEBHOOK_FALLBACK_ENABLED.
Naming: <NAME>-YYYY-MM-DD.jsonl in XENDIT_WEBHOOK_FALLBACK_DIR (default
./logs), basename XENDIT_WEBHOOK_FALLBACK_NAME (default
xendit-webhook-fallback). No stdout fallback by design.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

backend/test/routes/shared.payment-webhooks.routes.test.js

@@ -187,4 +187,179 @@ describe('POST /api/shared/payment/webhooks/xendit', () => {
     const [row] = await db()`SELECT status FROM payment_requests WHERE id = ${session.id}`
     expect(row.status).toBe(PaymentRequestStatus.PENDING)
   })
+
+  // --- Survival logging --------------------------------------------------
+  // Every inbound webhook lands in `webhook_logs` BEFORE auth/validation, so
+  // we keep a forensic record on rejects, unknown payments, and exceptions.
+  describe('webhook_logs survival audit', () => {
+    const latestLog = async () => {
+      const rows = await db()`SELECT * FROM webhook_logs ORDER BY received_at DESC LIMIT 1`
+      return rows[0]
+    }
+
+    it('PAID: logs row with parsed primary fields + outcome stamped', async () => {
+      const session = await requestPayment({
+        productType: 'chat_session',
+        customerId: customer.id, durationMinutes: 12, amount: 50_000,
+      })
+
+      await fireWebhook(app, {
+        id: 'inv_log_paid',
+        external_id: session.id,
+        status: 'PAID',
+        amount: 50_000,
+        currency: 'IDR',
+        payment_method: 'BCA',
+        paid_at: '2026-05-25T10:00:00.000Z',
+        metadata: { app: 'halobestie_v2' },
+      })
+
+      const log = await latestLog()
+      expect(log.provider).toBe('xendit')
+      expect(log.callback_token_valid).toBe(true)
+      expect(log.xendit_event_id).toBe('inv_log_paid')
+      expect(log.external_id).toBe(session.id)
+      expect(log.payment_request_id).toBe(session.id)
+      expect(log.status).toBe('PAID')
+      expect(Number(log.amount)).toBe(50_000)
+      expect(log.currency).toBe('IDR')
+      expect(log.payment_method).toBe('BCA')
+      expect(log.paid_at).not.toBeNull()
+      expect(log.metadata_app).toBe('halobestie_v2')
+      expect(log.http_status).toBe(200)
+      expect(log.processing_result).toBe('confirmed')
+      expect(log.processing_error).toBeNull()
+      expect(log.processed_at).not.toBeNull()
+      // raw_body is verbatim — unknown future fields would land here
+      expect(log.raw_body.metadata.app).toBe('halobestie_v2')
+    })
+
+    it('401 invalid token still logs a row with callback_token_valid=false', async () => {
+      const res = await fireWebhook(
+        app,
+        { id: 'inv_log_401', external_id: 'whatever', status: 'PAID', amount: 1 },
+        'wrong-token-but-same-length-padding',
+      )
+      expect(res.statusCode).toBe(401)
+
+      const log = await latestLog()
+      expect(log.callback_token_valid).toBe(false)
+      expect(log.http_status).toBe(401)
+      expect(log.processing_result).toBe('rejected_invalid_token')
+      // Raw body still captured even though the request was rejected
+      expect(log.raw_body.id).toBe('inv_log_401')
+    })
+
+    it('redacts x-callback-token in stored headers', async () => {
+      await fireWebhook(app, { id: 'inv_redact', external_id: 'x', status: 'PAID', amount: 1 })
+      const log = await latestLog()
+      expect(log.headers['x-callback-token']).toBe('[REDACTED]')
+      // Non-secret headers are kept (e.g. content-type)
+      expect(log.headers['content-type']).toMatch(/application\/json/)
+    })
+
+    it('amount mismatch (409) logs rejected_amount_mismatch', async () => {
+      const session = await requestPayment({
+        productType: 'chat_session',
+        customerId: customer.id, durationMinutes: 12, amount: 50_000,
+      })
+      const res = await fireWebhook(app, {
+        id: 'inv_log_mismatch', external_id: session.id, status: 'PAID', amount: 999,
+      })
+      expect(res.statusCode).toBe(409)
+
+      const log = await latestLog()
+      expect(log.http_status).toBe(409)
+      expect(log.processing_result).toBe('rejected_amount_mismatch')
+      expect(Number(log.amount)).toBe(999)
+    })
+
+    it('unknown payment_request still logs ignored_unknown_payment_request', async () => {
+      await fireWebhook(app, {
+        id: 'inv_log_orphan',
+        external_id: '00000000-0000-0000-0000-000000000000',
+        status: 'PAID',
+        amount: 50_000,
+      })
+      const log = await latestLog()
+      expect(log.processing_result).toBe('ignored_unknown_payment_request')
+      expect(log.payment_request_id).toBe('00000000-0000-0000-0000-000000000000')
+    })
+
+    it('missing external_id logs ignored_no_external_id with payment_request_id NULL', async () => {
+      await fireWebhook(app, { id: 'evt_nox', status: 'SOMETHING' })
+      const log = await latestLog()
+      expect(log.processing_result).toBe('ignored_no_external_id')
+      expect(log.external_id).toBeNull()
+      expect(log.payment_request_id).toBeNull()
+    })
+
+    it('non-UUID external_id ACKs 200 and logs ignored_non_uuid_external_id', async () => {
+      const res = await fireWebhook(app, {
+        id: 'inv_log_legacy',
+        external_id: 'legacy-old-app-id-42',
+        status: 'PAID',
+        amount: 1,
+      })
+      expect(res.statusCode).toBe(200)
+      expect(res.json().ignored).toBe('non_uuid_external_id')
+
+      const log = await latestLog()
+      expect(log.external_id).toBe('legacy-old-app-id-42')
+      expect(log.payment_request_id).toBeNull()
+      expect(log.processing_result).toBe('ignored_non_uuid_external_id')
+      expect(log.http_status).toBe(200)
+    })
+
+    it('logs raw_body verbatim including unknown fields', async () => {
+      const session = await requestPayment({
+        productType: 'chat_session',
+        customerId: customer.id, durationMinutes: 12, amount: 50_000,
+      })
+      await fireWebhook(app, {
+        id: 'inv_log_extra',
+        external_id: session.id,
+        status: 'PAID',
+        amount: 50_000,
+        future_field_we_dont_know_yet: { nested: ['anything', 42] },
+        metadata: { app: 'halobestie_v2', extra: 'preserved' },
+      })
+      const log = await latestLog()
+      expect(log.raw_body.future_field_we_dont_know_yet.nested).toEqual(['anything', 42])
+      expect(log.raw_body.metadata.extra).toBe('preserved')
+      expect(log.metadata_app).toBe('halobestie_v2')
+    })
+
+    it('survives processing exceptions: logs processing_error + http_status=500', async () => {
+      // Force an exception by stubbing getPayment to throw. The survival
+      // contract is that even when the handler errors, the forensic row is
+      // intact and stamped — Xendit will retry on its own, but we have the
+      // record either way.
+      const paymentSvc = await import('../../src/services/payment.service.js')
+      const orig = paymentSvc.getPayment
+      const stub = vi.spyOn(paymentSvc, 'getPayment').mockImplementation(async () => {
+        throw new Error('synthetic_db_outage')
+      })
+      try {
+        const res = await fireWebhook(app, {
+          id: 'inv_boom',
+          external_id: '11111111-1111-1111-1111-111111111111',
+          status: 'PAID',
+          amount: 50_000,
+        })
+        expect(res.statusCode).toBe(500)
+
+        const log = await latestLog()
+        expect(log.http_status).toBe(500)
+        expect(log.processing_result).toBe('error')
+        expect(log.processing_error).toBe('synthetic_db_outage')
+        expect(log.xendit_event_id).toBe('inv_boom')
+        // Raw body is still there even though processing blew up
+        expect(log.raw_body.id).toBe('inv_boom')
+      } finally {
+        stub.mockRestore()
+        void orig
+      }
+    })
+  })
 })