Inbound webhooks

Webhooks in engage-ai run one way: messaging platforms call engage-ai. When a customer messages your WhatsApp number or Telegram bot, the platform sends the message to your connection's webhook URL. Your own application does not call these endpoints, and engage-ai does not currently send webhooks to you.

The URL

POST /channels/connect returns the URL to register:

https://api.getengageai.app/webhooks/{providerKey}?connection={externalAccountId}

For example https://api.getengageai.app/webhooks/telegram_bot?connection=7654321.

• providerKey selects the platform. One route serves every platform.
• ?connection= identifies which of your accounts the request is for. Keep it when you paste the URL; without it, verification fails.

What happens on each request

1. Verify. The request is checked with the connection's own credential: the HMAC signature made with your WhatsApp app secret, or the secret token you chose for Telegram. The check uses the exact bytes received.
2. Store. The raw event is saved before anything else, so it can be replayed if processing fails.
3. Acknowledge. The platform gets 200 within about 50 ms.
4. Process. Everything else (contact, conversation, retrieval, reply) happens on a queue afterwards.

Duplicates are ignored. Platforms redeliver events. Each event is stored once, keyed by the platform's own event id, so a redelivery does nothing.

Responses

The verification handshake

Some platforms check the URL before sending any events. Meta sends a GET with hub.mode, hub.verify_token and hub.challenge. engage-ai echoes the challenge back only if hub.verify_token equals the verifyToken you set when connecting. Platforms without a handshake get a plain 200.

Simulate a message

You can test the whole pipeline without a real platform by posting a Telegram-shaped update yourself. Use the secret token you set as webhookSecretToken:

curl -X POST "https://api.getengageai.app/webhooks/telegram_bot?connection=7654321" \
  -H "Content-Type: application/json" \
  -H "X-Telegram-Bot-Api-Secret-Token: <your webhookSecretToken>" \
  -d '{
    "update_id": 1,
    "message": {
      "message_id": 1,
      "date": 1758196800,
      "text": "Do the Trailhead boots come in UK 11?",
      "chat": { "id": 555000 },
      "from": { "id": 555000, "first_name": "Jamie" }
    }
  }'

A conversation with Jamie appears in GET /conversations and, after a few seconds, a draft or reply. Change update_id for each new test message; repeating one is treated as a redelivery and ignored.

Troubleshooting