Skip to main content
Use Self-host when you want to run the open-source gateway on your own infrastructure. You operate one Meta app, one API key and one subscriber webhook, and you can connect the phone lines that app allows. This is not the Cloud account. Cloud lives at app.watahub.dev and is documented in the rest of this site. If you only want a Watahub API key and a hosted connect page, go back to the introduction and follow Cloud.

​
What you run

The core is the public Hub-Ventures/watahub repository, also published as watahub on npm (0.2.0). It runs on Cloudflare Workers or Node.js 20+. The license is MIT. You configure your Meta app secret, a webhook verify token and a Watahub API key of 32 or more characters. The gateway stores each line’s Meta token and never returns it. Your agent receives each normalized event at SUBSCRIBER_WEBHOOK_URL and replies with POST /v1/messages against your gateway host, not https://cloud.watahub.dev.

​
First run locally

You need Node.js 20 or later, pnpm (corepack enable uses the version pinned in the repository) and a Meta app with the WhatsApp product.
Generate WATAHUB_API_KEY and SUBSCRIBER_WEBHOOK_SECRET:
Fill in .env. The gateway reads process.env and does not load .env by itself, so start it with Node’s --env-file:
A healthy process returns JSON with status ok, service watahub and version 0.2.0. The full walkthrough — Meta app, first send, first inbound webhook and Embedded Signup — is in the core Getting started guide. For Cloudflare Workers, Node, Docker or a reverse proxy, use Deployment.

​
Connect a line

On Self-host you finish a line with POST /v1/onboarding/connect (the Embedded Signup code, WABA id, phone number id and PIN) or with a system user token in META_SYSTEM_USER_TOKEN. See Getting started. Cloud customers instead use hosted setup links. Those pages do not apply here.

​
Webhooks

The core forwards one signed POST per Meta delivery to your single subscriber URL. The headers are x-watahub-signature (sha256= plus the lowercase hex HMAC-SHA256 of the exact body, keyed with SUBSCRIBER_WEBHOOK_SECRET), x-watahub-delivery-id, and Idempotency-Key (the same value as the delivery id). Deduplicate on x-watahub-delivery-id. The event catalog is in Webhooks and events. Do not follow the Cloud webhooks page for this. That page documents developer webhooks on cloud.watahub.dev: X-Webhook-Event, X-Webhook-Signature without a sha256= prefix, and X-Idempotency-Key. An older administrative destination on Cloud can look similar to the core subscriber; it is not the Self-host guide.

​
What stays on Cloud

The hosted Inbox, seven-day logs, token custody for many tenants, hosted setup links, developer webhooks, the CLI and MCP ship with Cloud / Enterprise Edition, not with the open-source core.

​
Official core guides