Insider Whatsapp Webhooks

generated: '2026-08-13'
method: searched
source: https://academy.insiderone.com/docs/webhooks-for-transactional-whatsapp
sources:
- https://academy.insiderone.com/docs/webhooks-for-transactional-whatsapp
- https://academy.insiderone.com/docs/webhooks-for-conversational-whatsapp
- https://academy.insiderone.com/docs/webhooks-for-otp-whatsapp
- https://academy.insiderone.com/docs/whatsapp-settings
- postman/insider-one-apis.postman_collection.json
asyncapi_published: false
asyncapi_note: >-
  Insider One publishes no AsyncAPI, no CloudEvents profile and no event schema registry. The event
  surface below is documented in prose + sample payloads only, so this artifact captures the webhook
  CATALOG rather than a machine-readable event contract. Nothing here is fabricated: every event
  name, field and payload shape is verbatim from Insider One's own webhook reference.
summary: >-
  The only outbound event surface Insider One publishes is WhatsApp message-status webhooks, in
  three flavours — Transactional, Conversational and Verify (OTP). Delivery-state events are
  forwarded from Meta's WhatsApp Cloud API and correlated back to the send call by an Insider-issued
  tracking "key". Webhooks are registered in the InOne panel (WhatsApp Settings > Account APIs) or,
  for the v2 OAuth 2.0 surface, through the gateway API.

surfaces:
  registration_ui: https://academy.insiderone.com/docs/whatsapp-settings
  registration_api:
  - {operation: updateTransactionalWhatsappWebhookSettingsWithOauth20, method: POST, url: 'https://gw.useinsider.com/api/wa/v2/transactional/settings', spec: openapi/insider-gateway-openapi.yml}
  - {operation: updateConversationalWhatsappWebhookSettingsWithOauth20, method: POST, url: 'https://gw.useinsider.com/api/wa/v2/conversational/settings', spec: openapi/insider-gateway-openapi.yml}

registration:
  transport: HTTPS POST to a subscriber-supplied webhook_url
  auth_methods:
  - {id: bearer, description: 'Bearer Token authentication — webhook URL + bearer token, configured per API type.'}
  - {id: oauth2, description: 'OAuth 2.0 — webhook URL, server token URL, client id/secret; grant types client_credentials or refresh_token; scopes e.g. webhook.write.'}
  api_types: [Conversational, Transactional, Verify]
  api_type_immutable: true
  limits:
    max_total: 20
    max_bearer: 10
    max_oauth2: 10
    duplicates_allowed: false
  settings_payload_fields: [webhook_url, from, auth_type, oauth2.grant_type, oauth2.token_url, oauth2.client_id, oauth2.client_secret, oauth2.refresh_token, oauth2.scopes, oauth2.expires_in]
  operational_warning: >-
    Changing a webhook URL immediately breaks any chatbot or automation flow bound to the previous
    URL. Insider One does not fan out to both during a cutover.

events:
- {name: sent, api_types: [Transactional, Conversational, Verify], description: 'Message accepted by WhatsApp.'}
- {name: delivered, api_types: [Transactional, Conversational, Verify], description: 'Delivered to at least one of the user devices. A single message can produce both delivered and failed when the user is signed in on multiple devices.'}
- {name: read, api_types: [Transactional, Conversational, Verify], description: 'Message read by the recipient.'}
- {name: failed, api_types: [Transactional, Conversational, Verify], description: 'Meta returned an error for the message; the Meta error object is forwarded verbatim.'}
- {name: reply, api_types: [Conversational], mandatory: true, description: 'Inbound reply from the user. Mandatory for Conversational webhooks and cannot be removed. Unsupported for the Verify API type.'}

payloads:
- id: accepted
  when: message accepted by WhatsApp
  fields:
  - {name: messaging_product, type: string, required: true, description: 'whatsapp'}
  - {name: contacts, type: array, required: true}
  - {name: 'contacts[].input', type: string, required: true, description: "User's phone number"}
  - {name: 'contacts[].wa_id', type: string, required: true, description: "Customer's WhatsApp ID"}
  - {name: messages, type: array, required: true}
  - {name: 'messages[].id', type: string, required: true, description: 'Message ID received by the business'}
  - {name: key, type: string, required: true, description: 'Insider One message tracking key, echoed in every later event for this message'}
- id: error
  when: WhatsApp returned an error for the message
  fields:
  - {name: error.message, type: string, required: true, description: 'e.g. "(#130429) Rate limit hit"'}
  - {name: error.type, type: string, required: true, description: 'e.g. OAuthException'}
  - {name: error.code, type: integer, required: true, description: 'Meta numeric error code'}
  - {name: error.fbtrace_id, type: string, required: false, description: 'Meta trace id for Direct Support'}
  - {name: error.error_data, type: object, required: false, description: 'Optional supplementary context; rely on code + message'}
  - {name: key, type: string, required: true}

correlation:
  id: key
  issued_by: Insider One
  returned_on: the send response
  present_on: every webhook event for that message
  note: >-
    This is the only end-to-end correlation identifier Insider One publishes anywhere — there is no
    request-id header on the REST responses.

delivery_semantics:
  send_response_meaning: accepted and queued, not delivered
  duplicate_states: 'A single message may report delivered on one device and failed on another.'
  missing_reports: >-
    "Delivery Report Missing" covers messages for which Meta never sends an event; those outcomes
    never arrive over either the Transactional or Conversational webhook.

other_event_surfaces:
- {name: 'MindBehind Live webhook service', docs: 'https://academy.insiderone.com/docs/mindbehind-live-webhook-service', description: 'Real-time conversation events from the MindBehind conversational product to subscriber endpoints.'}
- {name: 'Call an API (Architect journey channel)', docs: 'https://academy.insiderone.com/docs/architect-channel-call-an-api', description: 'OUTBOUND-BY-JOURNEY, not a webhook: an Architect journey element that calls a subscriber-defined endpoint mid-journey, with its own auth, throttling (requests/second) and response-check step.'}

gaps:
- No AsyncAPI, no event schema registry, no signature/HMAC verification documented on inbound webhooks
  (authentication is by the subscriber's own bearer token or OAuth credential, which authenticates
  Insider TO you, not the payload).
- No retry/backoff policy published for failed webhook deliveries.
- No webhook surface at all for Email, SMS, Web Push, App Push or Architect journey events — those
  outcomes are only readable by polling the analytics APIs.