Proof of Care Webhook — Setup Guide

What this does

Receives WhatsApp videos from outreach workers → uploads to YouTube → calls smart contracts on Base → updates your Google Sheet → replies to the worker.

Step 1 — Set up Meta WhatsApp Business API (20 minutes)

1. Go to developers.facebook.com and log in with Facebook
2. Click My Apps → Create App
3. Choose Business as the app type
4. Give it a name (e.g. “POC Webhook”)
5. On the dashboard, click Add Product → find WhatsApp → click Set Up
6. You’ll see a Test phone number — this is your POC WhatsApp number for development
7. Note down:
   • Phone Number ID (looks like 123456789012345)
   • Temporary Access Token (copy this — you’ll convert it to a permanent one later)
8. Under Webhooks, you’ll set the URL after Step 3

Getting a Permanent Access Token:

• Go to System Users in your Meta Business Manager
• Create a system user → generate a token with whatsapp_business_messaging permission
• This token does not expire — use this in your .env

Step 2 — Set up Google Service Account (10 minutes)

This allows the webhook to read/write your Google Sheet and upload to YouTube.

1. Go to console.cloud.google.com
2. Create a new project (e.g. “poc-webhook”)
3. Enable these two APIs:
   • Google Sheets API (search for it → Enable)
   • YouTube Data API v3 (search for it → Enable)
4. Go to IAM & Admin → Service Accounts → Create Service Account
5. Give it a name, click Create
6. Click the service account → Keys → Add Key → JSON
7. A JSON file downloads — this is your GOOGLE_SERVICE_ACCOUNT_JSON
8. Open the JSON file → copy the entire contents into your .env

Share your Google Sheet with the service account:

• Open your spreadsheet
• Click Share
• Paste the service account email (ends in @…iam.gserviceaccount.com)
• Give it Editor access

Add two new tabs to your sheet:

• A tab named exactly Workers with these column headers in row 1: phone | worker_code | name | trust | wallet | rating | cases | registered_date
• Your existing Children tab (rename if needed) — the webhook writes to columns A-L

Step 3 — Deploy to Railway (5 minutes)

1. Push this code to a GitHub repository
   • Go to github.com → New repository → upload these files
2. Go to railway.app → Sign in with GitHub
3. Click New Project → Deploy from GitHub repo
4. Select your repository
5. Railway detects it’s a Node.js app and deploys automatically
6. Click your deployment → Variables tab
7. Add every variable from .env.example with your real values
8. Your webhook URL will be something like: https://poc-webhook-production.up.railway.app

Step 4 — Connect Meta to your webhook URL (5 minutes)

1. Back in the Meta Developer portal → your App → WhatsApp → Configuration
2. Under Webhooks, click Edit
3. Set Callback URL: https://your-railway-url.up.railway.app/webhook
4. Set Verify Token: the same value as WHATSAPP_VERIFY_TOKEN in your .env
5. Click Verify and Save
6. Subscribe to the messages webhook field

If verification passes (you’ll see a ✓), your webhook is live.

Step 5 — Add your first worker to the Workers sheet

Add a row manually:

Phone must include country code with + prefix.

Step 6 — Test it

Send a video to your test WhatsApp number (the one from Meta’s dashboard). You should receive a reply within 90 seconds.

Test sequence:

1. Send a video (no caption) → should register a new child and reply with TZ-XXXXX
2. Send a text: STATUS TZ-XXXXX → should return the child’s current stage
3. Send a video with caption TZ-XXXXX DURING → should process surgery proof

File structure

poc-webhook/

├── server.js          ← Entry point — starts the web server

├── src/

│   ├── processor.js   ← Brain — decides what to do with each message

│   ├── whatsapp.js    ← Meta API — send/receive messages and videos

│   ├── sheets.js      ← Google Sheets — read/write records

│   ├── youtube.js     ← YouTube — upload videos automatically

│   └── contract.js    ← Smart contracts — register/update on Base blockchain

├── package.json

├── .env.example       ← Copy to .env and fill in your values

└── README.md

Common issues

“Webhook verification failed” → Check WHATSAPP_VERIFY_TOKEN in Railway matches what you entered in Meta

“Your number is not registered” → Add the worker’s phone to the Workers sheet with + prefix

“YouTube upload failed” → Make sure the YouTube channel is linked to the same Google account as your service account, and YouTube Data API v3 is enabled

“Contract call failed (non-fatal)” → This is expected until you fill in CONTRACT_OUTCOME_ADDRESS. The Google Sheet still records everything correctly. Add the contract address when you’ve deployed to Base.

Costs