One LINE Official Account, Multiple Tools: Webhook and Token Architecture

A completed WhatsApp Embedded Signup dialog does not mean that a customer is ready to send and receive messages.

The browser flow may have finished while the backend still has one of these problems:

• The result was attached to the wrong tenant


• The access token belongs to another app


• The wrong WhatsApp Business Account was selected


• The system user lacks the required access


• The phone number is not ready


• The app is not subscribed to WABA webhooks


• The first webhook cannot be routed to the customer

A SaaS application should display Connected only after every backend gate has passed.

Model onboarding as a state machine

Avoid representing onboarding with one Boolean field such as:

connected: true

Use explicit states instead:

type WhatsAppOnboardingStatus =

  | "started"

  | "browser_finished"

  | "token_validated"

  | "waba_resolved"

  | "access_verified"

  | "phone_ready"

  | "app_subscribed"

  | "webhook_pending"

  | "active"

  | "verification_required"

  | "failed";

A safe transition path is:

started

   ↓

browser_finished

   ↓

token_validated

   ↓

waba_resolved

   ↓

access_verified

   ↓

phone_ready

   ↓

app_subscribed

   ↓

webhook_pending

   ↓

active

Each transition should store evidence, not just a timestamp.

Define the acceptance gates

Meta's

Originally published on UnifyPort.

This article was prepared with AI assistance for language and structure, then technically reviewed and verified by the author.