Add Arc Receipts Webhook Inbox + Replay

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Arc Receipts MVP with invoice memos, receipt matching, in-memory ledger, and signed webhook helpers.
 - Arc Testnet watcher for memo-wrapped USDC payments, plus memo payment request helpers and official Arc Testnet contract constants.
+- Webhook Inbox + Replay for local signed-webhook delivery verification and replay attempts.
 
 ## [0.2.0-alpha] - 2026-06-02
 

README.md

@@ -303,12 +303,15 @@ Invoice, transaction memo, watcher, receipt, and signed webhook helpers for Arc
 import {
   ArcReceiptWatcher,
   ReceiptLedger,
+  WebhookInbox,
   createInvoiceMemo,
   createMemoPaymentRequest,
   verifyWebhookSignature,
 } from '@arc-nano-kit/sdk/receipts';
 ```
 
+`WebhookInbox` lets local apps receive a signed `invoice.paid` webhook, verify the signature, store the delivery attempt, and replay the same event while developing payment operations.
+
 ## 🌐 Why Arc?
 
 Arc is Circle's Layer 1 blockchain — purpose-built for stablecoin-native finance. Here's why it's the ideal foundation for usage-based billing:

ROADMAP.md

@@ -37,6 +37,7 @@ arc-nano-kit is under active development. This roadmap outlines our planned mile
 - [x] Receipt matching and in-memory ledger
 - [x] HMAC-signed webhook events
 - [x] Arc Testnet payment watcher
+- [x] Local webhook inbox and replay attempts
 - [ ] Persistent watcher cursor
 - [ ] SQLite/Postgres receipt store
 - [ ] Next.js webhook route helpers

apps/demo/src/app/api/receipts/route.ts

@@ -3,13 +3,13 @@ import {
   createMemoPaymentRequest,
   signWebhookEvent,
 } from '@arc-nano-kit/sdk/receipts';
+import { DEMO_WEBHOOK_SECRET, DEMO_WEBHOOK_TARGET } from '../webhook-inbox/store';
 
 export const dynamic = 'force-dynamic';
 
 const DEMO_SELLER = '0x1111111111111111111111111111111111111111';
 const DEMO_PAYER = '0x2222222222222222222222222222222222222222';
 const DEMO_TX_HASH = '0x7a6d91b9f5b42e6f9a4d8d5c0a5f1a833f9f94c8b2e7d4d0a0e8c7b6a5f4d3c2';
-const WEBHOOK_SECRET = 'arc_receipts_demo_secret';
 
 export async function GET() {
   const now = Date.now();
@@ -62,7 +62,7 @@ export async function GET() {
     );
   }
 
-  const signature = signWebhookEvent(paidEvent, WEBHOOK_SECRET);
+  const signature = signWebhookEvent(paidEvent, DEMO_WEBHOOK_SECRET);
 
   return Response.json({
     generatedAt: new Date().toISOString(),
@@ -117,8 +117,9 @@ export async function GET() {
     webhook: {
       eventId: paidEvent.id,
       type: paidEvent.type,
+      event: paidEvent,
       signatureHeader: signature.header,
-      target: 'https://seller.app/webhooks/arc',
+      target: DEMO_WEBHOOK_TARGET,
     },
     timeline: [
       {

apps/demo/src/app/api/webhook-inbox/replay/route.ts

@@ -0,0 +1,29 @@
+import type { WebhookEvent } from '@arc-nano-kit/sdk/receipts';
+import { DEMO_WEBHOOK_SECRET, DEMO_WEBHOOK_TARGET, webhookInbox } from '../store';
+
+export const dynamic = 'force-dynamic';
+
+interface ReplayRequest {
+  event?: WebhookEvent;
+  replayOf?: string;
+}
+
+export async function POST(request: Request) {
+  const body = (await request.json()) as ReplayRequest;
+
+  if (!body.event) {
+    return Response.json(
+      { error: 'Missing webhook event' },
+      { status: 400 },
+    );
+  }
+
+  const delivery = webhookInbox.replay({
+    event: body.event,
+    secret: DEMO_WEBHOOK_SECRET,
+    target: DEMO_WEBHOOK_TARGET,
+    replayOf: body.replayOf,
+  });
+
+  return Response.json({ delivery });
+}

apps/demo/src/app/api/webhook-inbox/route.ts

@@ -0,0 +1,24 @@
+import { DEMO_WEBHOOK_SECRET, DEMO_WEBHOOK_TARGET, webhookInbox } from './store';
+
+export const dynamic = 'force-dynamic';
+
+export async function POST(request: Request) {
+  const payload = await request.text();
+  const header = request.headers.get('x-arc-signature');
+
+  if (!header) {
+    return Response.json(
+      { error: 'Missing x-arc-signature header' },
+      { status: 400 },
+    );
+  }
+
+  const delivery = webhookInbox.receive({
+    payload,
+    header,
+    secret: DEMO_WEBHOOK_SECRET,
+    target: DEMO_WEBHOOK_TARGET,
+  });
+
+  return Response.json({ delivery });
+}

apps/demo/src/app/api/webhook-inbox/store.ts

@@ -0,0 +1,10 @@
+import { WebhookInbox } from '@arc-nano-kit/sdk/receipts';
+
+export const DEMO_WEBHOOK_SECRET = 'arc_receipts_demo_secret';
+export const DEMO_WEBHOOK_TARGET = 'https://seller.app/webhooks/arc';
+
+const globalWebhookInbox = globalThis as typeof globalThis & {
+  __arcNanoKitWebhookInbox?: WebhookInbox;
+};
+
+export const webhookInbox = globalWebhookInbox.__arcNanoKitWebhookInbox ??= new WebhookInbox();