Skip to main content

Webhooks

This page describes how to enable and handle Communiktor webhooks.

Overview and activation​

  • Webhooks are configured per instance. In your Communiktor dashboard, open the instance settings and set the webhook URL for that instance.
  • Changes may require restarting the instance to take effect.
  • All webhook requests are sent as HTTP POST with Content-Type: application/json to your configured URL.

Delivery requirements and disabling logic​

  • Your endpoint must return HTTP 200 for each webhook request. Always respond 200 even if you queue work asynchronously.
  • If your endpoint results in 5 HTTP errors (non-2xx) for an instance, webhooks are automatically disabled on that instance until you fix the endpoint and re-enable them in the dashboard.

Request payload schema​

The POST body has the following structure:

  • event: string — Webhook event key
  • instance: string — The instance identifier emitting the event
  • data: object|null — Event-specific payload, or null

Example:

{
  "event": "message.received",
  "instance": "my-instance-1",
  "data": {
    "from": "14155552671",
    "group": false,
    "type": "text",
    "text": "Hello"
  }
}

Your endpoint should always return 200 OK with a simple body:

{
  "message": "ok",
  "success": true
}

Supported events​

The following events can be delivered:

  • message.received

    • label: Message received
    • description: Fired when the instance receives a new WhatsApp message from a contact or group. Restarting the instance is required to start capturing messages if it was previously inactive.

  • call.received

    • label: Call received
    • description: Triggered when the instance detects an incoming WhatsApp voice or video call. Useful for logging calls or building automated call-handling workflows.

  • message.sent

    • label: Message sent
    • description: Triggered when the instance successfully delivers a WhatsApp message to the intended recipient. Can be used for message tracking or delivery confirmation.

  • message.sent.failed

    • label: Message send failed
    • description: Triggered when the instance fails to deliver a WhatsApp message due to connection issues, invalid recipients, or other delivery errors.

  • instance.connected

    • label: Instance connected
    • description: Fired when the instance successfully establishes a connection to WhatsApp. This event confirms the instance is ready to send and receive messages.

  • instance.disconnected

    • label: Instance disconnected
    • description: Fired when the instance loses its connection to WhatsApp. This may occur due to network problems, device logouts, or unexpected shutdowns.

  • instance.stopped

    • label: Instance stopped
    • description: Fired when the instance is intentionally or automatically stopped. No further events will be triggered until it is restarted.

  • instance.qr.generated

    • label: QR generated
    • description: Fired when a new QR code is generated by the instance for authentication. The code must be scanned from the WhatsApp mobile app to establish a session.

Handling tips and best practices​

  • Validate the X-API-KEY if you choose to secure webhooks with a shared secret header (optional, if supported in your dashboard settings).
  • Respond 200 quickly and process heavy work asynchronously to avoid timeouts.
  • Implement observability: log event ids, types, and processing results.
  • Consider idempotency: if your system might receive duplicates, use the message id or your own idempotency keys.