1. Log every failed call to a file
hookmyapp channels logs records what HookMyApp forwarded to your webhook URL and what your endpoint answered. It does not record the calls your app makes to us, so your app has to record those itself.
Already logging somewhere? Use what you have, and make sure four fields land in the record: HTTP status, the HookMyApp error code, the x-request-id response header, and which direction the call went.
Nothing in place yet? One function, no dependency:
The gateway sets
x-request-id on every response and honors one you send. A support ticket that names a request id is faster to answer..gitignore and clear it between runs.
2. Set your alert phone
3. Handle limits by code
A403 with code CHANNEL_USAGE_LIMIT_EXCEEDED means your organization is over its plan allowance. Retrying cannot lift it. Only an upgrade or a top-up does.
Every rejected call tells you so. The response body is:
message straight through to whoever can act on it:
HookMyApp-generated errors use the flat envelope above. Other Meta rejections keep Meta’s nested
{ "error": { ... } } shape.
Retry a send without sending it twice
Meta has no protection against duplicate sends. If a send times out on your side, or you get504 GATEWAY_UPSTREAM_NO_ANSWER, the message may already be out, and a plain retry can send it again. Give each message an Idempotency-Key and send the same key on every retry of it:
Keys work on any POST, are scoped to your organization, and are kept for 24 hours. An attempt Meta refused or never received does not use up its key, so the retry goes through.
On WhatsApp, also put your own message id in
biz_opaque_callback_data. Meta returns it in that message’s status webhooks, so after an unknown outcome you can tell whether the message went out.
4. Keep the webhook route out of your auth middleware
HookMyApp is not a logged-in user of your app. If your webhook path sits behind session auth, an API-key gate, or a WAF rule, HookMyApp gets401 or 403 and every inbound message is lost.
X-HookMyApp-Signature-256 against WEBHOOK_HMAC_SECRET.
Answer fast, too. Return 200, then do the work. A slow handler becomes a 504 on our side and the message is recorded as undelivered.
5. Use the CLI tunnel, not a hand-rolled one
An always-on self-hosted deployment is a supported pattern: a personal server, a Raspberry Pi, a long-running agent.hookmyapp channels listen is built for it, with a per-channel access-controlled tunnel on a stable hostname.
A hand-rolled tunnel is not. Free tunnel services hand out a new random hostname on every restart, so the URL stored by webhook set stops working the moment the tunnel restarts, with nothing to announce it.
Use channels listen for a self-hosted or local destination, and a real HTTPS URL for a deployed backend.