Skip to content
engage-ai

API reference

Webhooks

Called by messaging platforms, not by your application

For concepts and a walkthrough, read Inbound webhooks.

Subscription handshake

GET/webhooks/{providerKey}

Answers the verification challenge some providers send before they will deliver events (Meta's hub.challenge, for example). Providers without a handshake get a plain 200. Called by the provider, not by your application.

Auth
None

Path parameters

  • providerKeystringrequired

    From GET /channels/providers, e.g. whatsapp_cloud.

Responses

  • 200The challenge echoed verbatim as text/plain, or `ok`.
  • 400No connector is registered for this provider key.
Request
curl "https://api.getengageai.app/webhooks/telegram_bot"

Receive events from a messaging platform

POST/webhooks/{providerKey}

Called by the provider, not by your application. Verifies the signature against the connection's own secret, stores the raw envelope and returns — all downstream work happens on a queue.

The request body is whatever the provider sends; each connector understands its own format, which is why this route is not schema-typed.

Always answers 200 except on a failed signature check: providers treat a non-2xx as a delivery failure and eventually disable the subscription, so a parsing bug on our side must never be expressed as a 500 to them. The raw event is durable and replayable either way.

Auth
None

Path parameters

  • providerKeystringrequired

    From GET /channels/providers, e.g. telegram_bot.

Response fields 200
  • statusenum

    One of accepted, duplicate, ignored, challenge

Responses

  • 200`accepted` (queued), `duplicate` (a redelivery we already hold), `ignored` (valid but not actionable, e.g. an unknown connection), or `challenge`.
  • 401Signature verification failed.
Request
curl -X POST "https://api.getengageai.app/webhooks/telegram_bot"
Response · 200
{
  "status": "accepted"
}