Build Escrow Payment Webhooks

## 📚 Overview
Develop backend listeners for Soroban escrow contract events to manage milestone payments, adapted to current database structure and project setup.

If you need coordination or clarification, use the project’s [[Telegram Group](https://t.me/+YZEXOc_LOzIyYTgx)](https://t.me/+YZEXOc_LOzIyYTgx).

---

## 🔍 Background
Required for triggering milestone releases, updating transaction records, dispute resolution processes, and ensuring secure blockchain interactions.

---

## 🛠 Requirements
- Create a POST `/webhooks/escrow` endpoint to receive Stellar Soroban callbacks
- Create a GET `/transactions/:id` endpoint to check transaction status
- Implement idempotency using a `webhook_events` table
- Modify `contracts` table:
- Add `blockchain_contract_id` (VARCHAR)
- Add `blockchain_network` (VARCHAR)
- Modify `transactions` table:
- Add `blockchain_tx_hash` (VARCHAR)
- Add `blockchain_status` (ENUM: pending, confirmed, failed)
- Create `webhook_events` table with:
- `id` (SERIAL PRIMARY KEY)
- `event_id` (VARCHAR UNIQUE NOT NULL)
- `event_type` (VARCHAR NOT NULL)
- `payload` (JSONB NOT NULL)
- `processed_at` (TIMESTAMP DEFAULT NOW())
- Verify blockchain signatures in webhook events

---

## 🔧 Implementation Plan

### 1. Create Feature Branch
```bash
git checkout -b feature-escrow-webhooks-[issue-number]
```

### 2. Schema Changes
- Update `contracts`, `transactions`, and create `webhook_events` table

### 3. Webhook Endpoint
- Implement POST `/webhooks/escrow`
- Parse and verify incoming events
- Store in `webhook_events` to ensure idempotency
- Update `milestones`, `transactions` based on event type

### 4. Transaction Status Endpoint
- Implement GET `/transactions/:id`
- Fetch and return blockchain status

### 5. Signature Verification
- Ensure events are cryptographically verified before processing

### 6. Testing
- Unit tests for webhook handling, idempotency, transaction updates (≥ 90% coverage)
- Test invalid payloads, duplicate events, signature validation

### 7. Commit and Push
```bash
git add .
git commit -m "Feature: Escrow contract event listener and transaction status endpoint"
git push origin feature-escrow-webhooks-[issue-number]
```

---

## ✅ Definition of Done
- [ ] Webhook POSTs are idempotent (event IDs stored and verified)
- [ ] `milestones` and `transactions` updated correctly
- [ ] `contracts` linked to blockchain escrow contracts
- [ ] Signature verification implemented
- [ ] Unit test coverage ≥ 90%
- [ ] Pull request meets template standards

---

## 📆 Timeframe
3 days

Start by reviewing the current project setup and database structure, then trace the entry points for POST /webhooks/escrow and GET /transactions/:id. Implementations are complete when webhook events are idempotent and signature-verified, milestones and transactions update correctly, the schema changes exist, and tests cover invalid, duplicate, and signature-failure cases.

Written by the indexing model from the issue text.