Initial Release
Receive WhatsApp Business text messages in an InterSystems IRIS production and send a configurable acknowledgement. Six ObjectScript classes provide the REST webhook, message type, business service, business operation, Graph HTTP adapter and example production. IRIS handles subscription verification, HMAC-SHA256 validation, event filtering and delivery. Python is used only by the local HTTP test client and simulated Graph endpoint.
Install Docker and obtain the IRIS for Health Community 2026.2 image, then run the following command from the project root. To use a different compatible image, set IRIS_IMAGE.
./tests/local-check.sh
The script starts an isolated container with external networking disabled and removes it on exit. It compiles the ObjectScript classes, registers the test REST application, starts a disposable production, and sends HTTP requests through the IRIS Web Gateway. It uses only synthetic credentials and phone numbers. No Python packages are installed.
The test covers valid and invalid challenges, invalid or missing signatures, malformed JSON, media and status notifications, other business numbers, and request size limits. A signed batch containing two Chinese texts is delivered twice, followed by a third text. The three distinct messages traverse the actual IRIS queue and outbound HTTP adapter. A loopback Graph server checks the destination path, recipient and reply body. Finally the script stops the production and checks that a new callback receives HTTP 503.
PASS: ObjectScript REST, 5 signed texts, 3 distinct Graph replies, stopped production -> 503
Use a dedicated interoperability-enabled IRIS or IRIS for Health namespace and a configured InterSystems Web Gateway. Mount the repository where IRIS can read it. Import the six source classes in the target namespace, replacing the directory if necessary.
set sc=$system.OBJ.LoadDir("/app/src","ck",,1)
do $system.Status.DisplayError(sc)
Set these secrets and identifiers in the environment of the IRIS instance before startup. The webhook and operation workers must see the values.
| Variable | Purpose |
|---|---|
WA_VERIFY_TOKEN |
Private token entered in Meta’s subscription configuration |
WA_APP_SECRET |
Meta application secret for signing webhook bodies |
WA_PHONE_ID |
Numeric business phone ID, used to filter notifications |
WA_ACCESS_TOKEN |
WhatsApp access token permitted to send from this business number |
In System Administration → Security → Applications → Web Applications, create a REST web application at /wa-text in the production namespace. Use the dispatch class WaText.Webhook, enable unauthenticated requests (Meta authenticates POSTs by signature), and disable static file serving. Grant the database permissions needed to run the classes and queue messages on this web application. The disposable test grants only %DB_USER on the application in the otherwise empty USER namespace. Select the application database role appropriate to your own namespace. The exact test registration is in tests/webapp.script.
Route /wa-text/webhook through your Web Gateway and publish this path via HTTPS for real Meta callbacks. Pass the raw body and X-Hub-Signature-256 unchanged. Set up access logs to omit query strings because subscription verification includes a private token. A reverse proxy can map an existing public /webhook to the internal /wa-text/webhook.
Configure an outbound IRIS TLS client profile with a trusted CA bundle and server-certificate verification set to Required. In the Management Portal, open WaText.Production and select WhatsApp Reply. Set adapter TLSConfig to the profile, PhoneId to the same numeric ID as WA_PHONE_ID, and GraphVersion to a version supported by your Meta app. Set operation ReplyText to customize the acknowledgement, apply the configuration and start the production.
In Meta’s WhatsApp settings, enter your public callback URL and the same verification token. Subscribe to the WhatsApp Business Account’s messages field. Check the app’s subscription to your account and authorize the recipient for your test number.
Send a text from an allowed phone to the business test number. In IRIS Message Viewer, inspect the session from WhatsApp Input to WhatsApp Reply. It contains the incoming Meta message ID, sender and text. With default settings the phone should receive Thanks, your text reached IRIS. A Graph message ID confirms acceptance; verify delivery on the phone. The local demonstration exercises the REST and production components with a simulated Graph endpoint. Live phone delivery requires a configured Meta account.
WaText.Webhook authenticates raw bytes before JSON decoding. It verifies the entire batch, selects text events for the configured business number, and returns HTTP 200 after IRIS queues all selected texts. If queuing fails partway, Meta can retry the batch after HTTP 503. The operation serializes deliveries for each inbound message ID and persists its receipt before the external call. Completed receipts suppress repeats. An uncertain or failed send leaves a pending receipt and an error in the production log. After verifying that Graph did not accept the send, an operator can clear that one pending receipt in the production namespace and resubmit the message. Retain receipts throughout Meta’s redelivery window and restrict access to sender IDs and text in Message Viewer.
Meta Webhooks · WhatsApp Business Platform · InterSystems %CSP.REST · Community Bounty idea