Connection events

When a customer finishes an onboarding link, you can find out two ways: the redirect on their browser, and a webhook to your server.

Redirects

We send the customer’s browser back to your redirect URL with query params attached.

Success

successRedirectUrl (or a HookMyApp page if you didn’t set one):

Param	Value
`status`	Always `completed`.
`phone_number_id`	The connected WhatsApp phone number ID. Omitted for Instagram.
`display_phone_number`	The connected WhatsApp number, formatted for display. Omitted for Instagram.
`externalId`	Your external ID for this link, if you set one.

Failure

failureRedirectUrl (or a HookMyApp page if you didn’t set one):

Param	Value
`status`	Always `failed`.
`reason`	Why it failed. See the table below.
`externalId`	Your external ID for this link, if you set one.

Reason codes

Reason	What happened	What to do
`customer_cancelled`	Your customer left or declined the Meta connect flow.	Resend the link.
`permission_denied`	Your customer didn’t grant the access WhatsApp or Instagram needs.	Ask them to retry and approve every permission.
`already_connected`	That number or account is already connected elsewhere.	Have them free it up, or connect a different number or account.
`no_number_available`	They finished Meta’s flow but have no WhatsApp number ready to connect.	Ask them to finish WhatsApp Business setup, then retry.
`link_inactive`	The link was revoked, already used, or its target customer no longer exists.	Mint a new link.
`temporary_failure`	A short-lived hiccup: rate limit, expired session, brief pause.	Ask them to try again in a few minutes.
`service_error`	Something went wrong on our side. We’re already alerted.	Contact support if it keeps happening.

Webhook events

Set connectedNotificationUrl when you create the link to get a server-to-server POST the moment your customer’s connect finishes, whether it succeeds or fails.

Events only go to connectedNotificationUrl. They are never mixed into your message destination webhook, which only carries inbound WhatsApp and Instagram messages.

channel.connected

{
  "event": "channel.connected",
  "externalId": "your-id",
  "channelType": "whatsapp",
  "channelPublicId": "ch_XXXXXXXX",
  "workspaceId": "ws_XXXXXXXX",
  "phoneNumberId": "106540000000002",
  "connectedAt": "2026-07-29T12:00:00.000Z"
}

phoneNumberId is null for Instagram.

channel.connect_failed

{
  "event": "channel.connect_failed",
  "externalId": "your-id",
  "channelType": "whatsapp",
  "reason": "permission_denied",
  "occurredAt": "2026-07-29T12:00:00.000Z"
}

reason is one of the codes above.

Headers

Every event POST carries:

Header	Value
`X-HookMyApp-Event`	`channel.connected` or `channel.connect_failed`
`X-HookMyApp-Signature-256`	`sha256=<hex>`, HMAC-SHA256 over the raw request body

Signature verification

Compute HMAC-SHA256 over the raw request body using the signing secret returned when you create, list, or regenerate the link.
This secret is separate from the Verify Token. The Verify Token is only used for the ownership handshake on your message destination webhook, never for signing.

import express from 'express'
import { createHmac, timingSafeEqual } from 'node:crypto'

const app = express()
const SIGNING_SECRET = process.env.CONNECTION_EVENT_SIGNING_SECRET

app.post(
  '/webhooks/hookmyapp-connect',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.get('X-HookMyApp-Signature-256') || ''
    const expected = 'sha256=' +
      createHmac('sha256', SIGNING_SECRET)
        .update(req.body)
        .digest('hex')

    const a = Buffer.from(signature)
    const b = Buffer.from(expected)
    if (a.length !== b.length || !timingSafeEqual(a, b)) {
      return res.sendStatus(401)
    }

    const payload = JSON.parse(req.body.toString('utf8'))
    if (payload.event === 'channel.connected') {
      // Your customer finished connecting.
    } else if (payload.event === 'channel.connect_failed') {
      // Your customer's connect failed. payload.reason explains why.
    }
    res.sendStatus(200)
  },
)

Retries

If your endpoint doesn’t answer with a 2xx, we retry up to 8 attempts, waiting longer between each one, from about a minute up to an hour. If every attempt fails, delivery stops.

Customer Messaging

API Reference

Redirects

Success

Failure

Reason codes

Webhook events

channel.connected

channel.connect_failed

Headers

Signature verification

Retries

​Redirects

​Success

​Failure

​Reason codes

​Webhook events

​channel.connected

​channel.connect_failed

​Headers

​Signature verification

​Retries

Redirects

Success

Failure

Reason codes

Webhook events

channel.connected

channel.connect_failed

Headers

Signature verification

Retries