Engagive API documentation

Channels · WhatsApp · Webhooks

Webhook payloads

After you register a URL under Webhook config, Engagive POSTs a stable envelope for that WhatsApp account's messages, statuses, reactions, and template Meta updates. Every POST includes api_version, event, event_id, account_id, timestamps, and data.

Delivery rules

  • Method: POST, header Content-Type: application/json
  • Headers also include X-Engagive-Event, X-Engagive-Event-Id, X-Engagive-Account-Id, X-Engagive-Api-Version (HMAC signing — see Webhook signing)
  • Timeout: ~10 seconds; non-2xx / timeouts are queued and retried with exponential backoff (default 4 attempts)
  • Only active URLs for that account — never another account's traffic; AppChat webhooks are separate
  • Media inbound is a single whatsapp.message.received after media_url is ready — no separate media event by default
  • whatsapp.meta.raw is opt-in only (not delivered by default)
  • Per-URL events subscription: omit / ["*"] receives all typed events; whatsapp.meta.raw only if explicitly listed
  • Inbound customer messages always use the envelope (whatsapp.message.received). Bare message-row POSTs without event are no longer sent.

Event catalog

eventWhen
whatsapp.message.receivedCustomer inbound message (after media_url is ready when applicable)
whatsapp.message.sentBusiness sends a message (portal, public API, campaign, AI, automation)
whatsapp.message.statusMeta delivery status: sent / delivered / read / failed
whatsapp.message.reactionReaction applied (customer via Meta, or business via portal/API)
whatsapp.template.statusMeta template approval status update
whatsapp.template.categoryMeta template category change
whatsapp.phone.qualityPhone quality / throughput update (Meta phone_number_quality_update)
whatsapp.phone.limitMessaging / phone capability limits (Meta business_capability_update)
whatsapp.account.updatedNormalized WABA account_update (ban, partner removed, etc.)
whatsapp.meta.rawOpt-in only: account-scoped Meta field + value (not default)

Received example

POST body — whatsapp.message.received
{
  "api_version": "2026-08-01",
  "event": "whatsapp.message.received",
  "event_id": "evt_01JEXAMPLE0000000000000001",
  "account_id": 3,
  "occurred_at": "2026-08-06T12:00:00.000Z",
  "delivered_at": "2026-08-06T12:00:00.050Z",
  "data": {
    "message": {
      "id": 1001,
      "whatsapp_message_id": "wamid.HBgMOTE5…",
      "parent_whatsapp_message_id": null,
      "contact_id": 42,
      "direction": "incoming",
      "message_type": "text",
      "status": "received",
      "error": null,
      "content": "Hi, I need help with my order",
      "caption": null,
      "media": null,
      "content_json": null,
      "reaction": null,
      "template": null,
      "created_at": "2026-08-06T12:00:00.000Z",
      "message_time": "2026-08-06T12:00:00.000Z"
    },
    "contact": {
      "id": 42,
      "wa_id": "923001234567",
      "name": "Ayesha"
    }
  }
}

Sent example

POST body — whatsapp.message.sent
{
  "api_version": "2026-08-01",
  "event": "whatsapp.message.sent",
  "event_id": "evt_01JEXAMPLE0000000000000003",
  "account_id": 3,
  "occurred_at": "2026-08-06T12:04:50.000Z",
  "delivered_at": "2026-08-06T12:04:50.040Z",
  "data": {
    "message": {
      "id": 1002,
      "whatsapp_message_id": "wamid.HBgMOTE5…",
      "parent_whatsapp_message_id": null,
      "contact_id": 42,
      "direction": "outgoing",
      "message_type": "text",
      "status": "sent",
      "error": null,
      "content": "Hello from business",
      "caption": null,
      "media": null,
      "content_json": null,
      "reaction": null,
      "template": null,
      "created_at": "2026-08-06T12:04:50.000Z",
      "message_time": "2026-08-06T12:04:50.000Z"
    },
    "contact": {
      "id": 42,
      "wa_id": "923001234567",
      "name": "Ayesha"
    }
  }
}

Status example

POST body — whatsapp.message.status
{
  "api_version": "2026-08-01",
  "event": "whatsapp.message.status",
  "event_id": "evt_01JEXAMPLE0000000000000002",
  "account_id": 3,
  "occurred_at": "2026-08-06T12:05:00.000Z",
  "delivered_at": "2026-08-06T12:05:00.080Z",
  "data": {
    "message": {
      "id": 1002,
      "whatsapp_message_id": "wamid.HBgMOTE5…",
      "parent_whatsapp_message_id": null,
      "contact_id": 42,
      "direction": "outgoing",
      "message_type": "text",
      "status": "failed",
      "error": {
        "code": null,
        "message": "Unsupported Sticker mime type image/jpeg.",
        "details": null
      },
      "content": "Hello from business",
      "caption": null,
      "media": null,
      "content_json": null,
      "reaction": null,
      "template": null,
      "created_at": "2026-08-06T12:04:50.000Z",
      "message_time": "2026-08-06T12:04:50.000Z"
    },
    "contact": {
      "id": 42,
      "wa_id": "923001234567",
      "name": "Ayesha"
    },
    "status": "failed",
    "status_timestamp": "2026-08-06T12:05:00.000Z",
    "error": {
      "code": null,
      "message": "Unsupported Sticker mime type image/jpeg.",
      "details": null
    }
  }
}

Reaction example

POST body — whatsapp.message.reaction
{
  "api_version": "2026-08-01",
  "event": "whatsapp.message.reaction",
  "event_id": "evt_01JEXAMPLE0000000000000004",
  "account_id": 3,
  "occurred_at": "2026-08-06T12:06:00.000Z",
  "delivered_at": "2026-08-06T12:06:00.030Z",
  "data": {
    "message": {
      "id": 1001,
      "whatsapp_message_id": "wamid.HBgMOTE5…",
      "parent_whatsapp_message_id": null,
      "contact_id": 42,
      "direction": "incoming",
      "message_type": "text",
      "status": "received",
      "error": null,
      "content": "Hi, I need help with my order",
      "caption": null,
      "media": null,
      "content_json": null,
      "reaction": {
        "incoming": "👍",
        "outgoing": null
      },
      "template": null,
      "created_at": "2026-08-06T12:00:00.000Z",
      "message_time": "2026-08-06T12:00:00.000Z"
    },
    "contact": {
      "id": 42,
      "wa_id": "923001234567",
      "name": "Ayesha"
    },
    "reaction": {
      "incoming": "👍",
      "outgoing": null
    }
  }
}

Template status example

POST body — whatsapp.template.status
{
  "api_version": "2026-08-01",
  "event": "whatsapp.template.status",
  "event_id": "evt_01JEXAMPLE0000000000000005",
  "account_id": 3,
  "occurred_at": "2026-08-06T13:00:00.000Z",
  "delivered_at": "2026-08-06T13:00:00.020Z",
  "data": {
    "template": {
      "name": "order_update",
      "language": "en_US",
      "wa_template_id": "1234567890",
      "status": "APPROVED",
      "reason": null
    },
    "wa_account_id": "WABA_ID_OR_NULL"
  }
}

Template category example

POST body — whatsapp.template.category
{
  "api_version": "2026-08-01",
  "event": "whatsapp.template.category",
  "event_id": "evt_01JEXAMPLE0000000000000006",
  "account_id": 3,
  "occurred_at": "2026-08-06T13:05:00.000Z",
  "delivered_at": "2026-08-06T13:05:00.020Z",
  "data": {
    "template": {
      "name": "order_update",
      "language": "en_US",
      "wa_template_id": "1234567890",
      "previous_category": "MARKETING",
      "new_category": "UTILITY"
    },
    "wa_account_id": "WABA_ID_OR_NULL"
  }
}

Phone quality example

POST body — whatsapp.phone.quality
{
  "api_version": "2026-08-01",
  "event": "whatsapp.phone.quality",
  "event_id": "evt_01JEXAMPLE0000000000000007",
  "account_id": 3,
  "occurred_at": "2026-08-06T14:00:00.000Z",
  "delivered_at": "2026-08-06T14:00:00.040Z",
  "data": {
    "phone": {
      "display_phone_number": "15550783881",
      "wa_phone_id": null
    },
    "event": "THROUGHPUT_UPGRADE",
    "current_limit": "TIER_UNLIMITED",
    "old_limit": null,
    "max_daily_conversations_per_business": null,
    "wa_account_id": "102290129340398"
  }
}

Phone limit example

POST body — whatsapp.phone.limit
{
  "api_version": "2026-08-01",
  "event": "whatsapp.phone.limit",
  "event_id": "evt_01JEXAMPLE0000000000000009",
  "account_id": 3,
  "occurred_at": "2026-08-06T14:02:00.000Z",
  "delivered_at": "2026-08-06T14:02:00.025Z",
  "data": {
    "phone": {
      "display_phone_number": null,
      "wa_phone_id": null
    },
    "current_limit": null,
    "old_limit": null,
    "max_daily_conversation_per_phone": "TIER_2K",
    "max_daily_conversations_per_business": "TIER_2K",
    "max_phone_numbers_per_business": null,
    "wa_account_id": "102290129340398"
  }
}

Account updated example

POST body — whatsapp.account.updated
{
  "api_version": "2026-08-01",
  "event": "whatsapp.account.updated",
  "event_id": "evt_01JEXAMPLE0000000000000008",
  "account_id": 3,
  "occurred_at": "2026-08-06T14:05:00.000Z",
  "delivered_at": "2026-08-06T14:05:00.030Z",
  "data": {
    "update_event": "PARTNER_REMOVED",
    "phone_number": null,
    "ban_info": null,
    "is_active": false,
    "wa_account_id": "102290129340398"
  }
}

Configure webhook URLs