Webhooks
Bot Webhook
This Webhook will be triggered when your customer sends a message to your Qiscus Omnichannel Chat.
{ "app_code": "kovof-123", "channel": { "id": 123, "name": "Qiscus 123", "source": "wa" }, "payload": { "from": { "avatar_url": "https://latest-multichannel.qiscus.com/img/default_avatar.svg", "email": "6281xxx132", "id": 0, "id_str": "0", "name": "Harpi" }, "message": { "comment_before_id": 0, "comment_before_id_str": "0", "created_at": "2025-07-11T05:46:37Z", "disable_link_preview": false, "extras": null, "id": 0, "id_str": "0", "payload": null, "text": "chat postman 2", "timestamp": "2025-07-11T05:46:37Z", "type": "text", "unique_temp_id": "wa_wamid.HBgNNjI4MTIxNzg0NDEzMhUCABIYIDJFMEFCQkEzRkVEEN0RFRjcyNTQ0ODkwMDJDQUM4MTU2AAAxaj==", "unix_nano_timestamp": 1752212797000, "unix_timestamp": 1752212797 }, "room": { "id": "123", "id_str": "123", "is_public_channel": false, "name": "Harpi", "options": "{\"channel\":\"wa\",\"channel_details\":{\"channel_id\":963,\"name\":\"Qiscus Cloud Group\",\"phone\":\"+62628771666489\"},\"is_resolved\":false,\"is_waiting\":true,\"source\":\"wa\"}", "participants": [ { "email": "6281xxx4132" }, { "email": "xxxn@xx.com" } ], "room_avatar": "https://latest-multichannel.qiscus.com/img/default_avatar.svg", "topic_id": "123", "topic_id_str": "123", "type": "group" }, "type": "post_comment_mobile" }, "type": "post_comment_mobile" // either type "post_comment_mobile" if from client side or "post_comment_rest" if from REST API}Custom Agent Allocation Webhook
This webhook will be triggered when your customer sends a message to your Qiscus Omnichannel Chat and has not been assign to the agent yet. Once your customer have at least an agent you will not get this webhook.
{ "app_code": "kovof-123", "app_id": "kovof-123", "avatar_url": "https://latest-multichannel.qiscus.com/img/default_avatar.svg", "candidate_agent": { "avatar_url": null, "created_at": "2022-09-28T06:34:39Z", "email": "xx@mail.com", "force_offline": false, "id": 2578, "is_available": true, "is_verified": false, "last_login": "2025-06-02T03:34:28Z", "name": "agen custom channel", "sdk_email": "sdNxxu@xx.com", "sdk_key": "xx", "type": 2, "type_as_string": "agent", "updated_at": "2025-07-09T02:31:27Z" }, "email": "628xx9406", "extras": "{\"user_properties\":[]}", "is_new_session": false, "is_resolved": false, "latest_service": null, "name": ".", "room_id": "123", "source": "wa", "channel": { "id": 123, "name": "Qiscus 123", "source": "wa" }}Custom Button
This webhook helps you to get information about a room chat into your third party systems, such as CRM, Ticketing, Analytics, and many more. This webhook is triggered when admin or supervisor or agent click custom button. Here's the sample response for this webhook.
{ "additional_info": [ { "anykey": "any value" }], "agent": { "email": "qixxxxti@gmail.com", "name": "Agent", "type": "admin" }, "channel_id": 0004, "channel_name": "Channel 1", "channel_type": "Qiscus Widget", "customer": { "avatar": "https://dxxx/xxxxxx-xxlient.png", "name": "Customer Name", "user_id": "email_customer@gmail.com" }, "customer_properties": [ { "id": 1, "label": "WEBSITE", "value": "" }, { "id": 2, "label": "ADDRESS", "value": "" }, { "id": 3, "label": "COMPANY", "value": "" } ], "notes": null, "room_id": 0000002, "tag": []}Mark As Resolved
This webhook helps you to get information about a room chat into your CRM or any other systems. Before you start, you need to register your webhook first. Please follow the example below :
URL :
[POST] https://omnichannel.qiscus.com/api/v1/app/webhook/mark_as_resolvedPlease follow this page to get your AdminToken
CURL Sample:
curl --location -g '{https://omnichannel.qiscus.com/api/v1/app/webhook/mark_as_resolved' \--header 'Authorization: {{AdminToken}}' \--header 'Qiscus-App-Id: {{AppCode}}' \--form 'webhook_url=""' \--form 'is_webhook_enabled=""'Sample Response:
{ "data": { "id": 123123123, "name": "Kipas Omnichannel Tester", "app_code": "test-testingomnichannel", "secret_key": "3e9f401ea7d65eea1etestingomnichannel", "created_at": "2020-03-16 06:53:19", "updated_at": "2021-12-29 08:51:31", "bot_webhook_url": "https://testingomnichannel.free.beeceptor.com", "is_bot_enabled": true, "allocate_agent_webhook_url": "https://testingomnichannel.free.beeceptor.com", "is_allocate_agent_webhook_enabled": true, "mark_as_resolved_webhook_url": "https://omnichannel.qiscus.com", "is_mark_as_resolved_webhook_enabled": true, "is_mobile_pn_enabled": true, "is_active": true, "is_sessional": true, "is_agent_allocation_enabled": false, "is_agent_takeover_enabled": true, "is_token_expiring": false, "paid_channel_approved": null, "use_latest": false }}This webhook will be triggered when admin or supervisor or agent resolves the conversation. Here's the sample of webhook responses.
Sample Webhook:
{ "app_code": "kovof-xxxxxx", "channel": { "id": 123, "name": "Qiscus xxxx", "source": "wa" }, "customer": { "additional_info": [], "avatar": "https://latest-multichannel.qiscus.com/img/default_avatar.svg", "name": "xxx", "user_id": "62851xxxxx" }, "resolved_by": { "email": "xxx@xx.com", "id": 123, "is_available": false, "name": "tester", "type": "admin" }, "service": { "first_comment_id": "", "id": 123, "is_resolved": true, "last_comment_id": "123", "notes": "ok", "room_id": "123", "source": "wa" }New Session Webhook
This webhook will be triggered when a customer sends a message to your Qiscus Omnichannel Chat for the first time or when a customer sends a new message after the previous chat room was resolved.
CURL Sample:
curl --location --request POST 'https://omnichannel.qiscus.com/api/v2/app/config/new_session_webhook' \--header 'Qiscus-Secret-Key: xxxx' \--header 'Qiscus-App-Id: xxx' \--form 'enabled="true"' \--form 'url="http://target.com"'Please follow this page to get Qiscus App ID and Qiscus Secret Key.
Sample Response:
{ "data": { "configs": { "is_new_session_webhook_enabled": "true", "new_session_webhook_url": "http://target.com" } }, "status": 200}A sample payload received when the New Session Webhook API is used.
{ "channel": { "id": 123, "name": "Qiscus xx", "source": "wa" }, "is_new_session": true, "payload": { "from": { "avatar_url": "https://latest-multichannel.qiscus.com/img/default_avatar.svg", "email": "6281xxx4132", "id": 0, "id_str": "0", "name": "Harpi" }, "message": { "id": 0, "id_str": "0", "payload": null, "text": "chat postman 2", "timestamp": "2025-07-10T09:46:03Z", "type": "text" }, "room": { "id": "123", "id_str": "123", "is_public_channel": false, "name": "Harpi", "options": "{\"channel\":\"wa\",\"channel_details\":{\"channel_id\":123,\"name\":\"Qiscus Cloud Group\",\"phone\":\"+62628771666489\"},\"is_resolved\":false,\"is_waiting\":true,\"source\":\"wa\"}", "participants": [ { "email": "6281217844132" }, { "email": "kovof-naquwyqeens0t0a_admin@qismo.com" } ], "room_avatar": "https://latest-multichannel.qiscus.com/img/default_avatar.svg", "topic_id": "123", "topic_id_str": "123", "type": "group" } }, "room_log": { "app_id": 123, "channel_id": 123, "created_at": "2025-07-10T09:46:02", "extras": { "user_properties": [] }, "has_no_message": false, "is_waiting": true, "name": "Harpi", "resolved": false, "room_badge": null, "room_id": "123", "source": "wa", "user_avatar_url": "https://latest-multichannel.qiscus.com/img/default_avatar.svg", "user_id": "628121xxx4132" }, "webhook_type": "NEW_SESSION_WEBHOOK"}User Logout Webhook
This webhook will be triggered when user (admin, supervisor, or agent) logout from Qiscus Omnichannel Chat dashboard. Before you start, you need to register your webhook first using this API.
URL :
[POST] {{BaseUrl}}/api/v2/app/config/auth_webhookCURL Sample:
curl --location -g --request POST '{{BaseUrl}}/api/v2/app/config/auth_webhook' \--header 'Authorization: {{AdminToken}}' \--form 'enabled=""' \--form 'url=""'Please follow this page to get your AdminToken.
Sample Response:
{ "data": { "configs": { "auth_webhook_url": "https://webhook.site/xxxxxxxxxxxx", "is_auth_webhook_enabled": "true" } }, "status": 200}Sample payload:
Admin
{ "payload": { "action": "logout", "timestamp": 1669004080, "user": { "avatar_url": null, "created_at": "2019-07-24T04:04:13", "email": "xxxxxxxxx@xxxxx.com", "force_offline": false, "id": 4xxx, "is_available": true, "is_verified": true, "last_login": "2022-11-21T02:59:27Z", "name": "Hana Tester Qiscus", "sdk_email": "xxxxxxxxadmin@xxxxx.com", "sdk_key": "dxxxx", "type": 1, "type_as_string": "admin", "updated_at": "2022-11-21T04:14:26" } }, "type": "auth"}Supervisor
{ "payload": { "action": "logout", "timestamp": 1669004271, "user": { "avatar_url": null, "created_at": "2022-08-12T03:01:50", "email": "xxxxx@xxxxx.com", "force_offline": false, "id": 1xxxxx, "is_available": true, "is_verified": false, "last_login": "2022-09-22T07:41:55Z", "name": "SPV", "sdk_email": "xxxxxspv@xxxxx.com", "sdk_key": "ex-xxxx-cxxxxxxx", "type": 3, "type_as_string": "supervisor", "updated_at": "2022-09-22T07:42:18" } }, "type": "auth"}Agent
{ "payload": { "action": "logout", "timestamp": 1669004379, "user": { "avatar_url": null, "created_at": "2022-08-12T03:02:18", "email": "xxxxx@xxxxx.com", "force_offline": false, "id": 1xxxxx, "is_available": true, "is_verified": false, "last_login": "2022-09-22T04:35:24Z", "name": "Agen", "sdk_email": "xxxxxagen@xxxxx.com", "sdk_key": "3x-xxxx-5xxxxxxx", "type": 2, "type_as_string": "agent", "updated_at": "2022-11-21T04:18:45" } }, "type": "auth"}You can get information regarding the Webhooks using the following CURL.
curl --location 'https://omnichannel.qiscus.com/api/v2/app/configs?show_all=true' \--header 'Qiscus-Secret-Key: xxxx' \--header 'Qiscus-App-Id: xxxx'Sample Response:
{ "data": { "configs": { "is_ig_story_mention_enabled:1268_enabled": true, "ig_story_mention_enabled:1265": "false", "ig_story_mention_enabled:1263": "false", "widget": null, "default_properties_created": "true", "is_waca_channel_enabled": true, "is_agent_send_outbound_message_inbox_enabled": true, "is_hide_agent_inbox_customer_id_enabled": true, "agent_send_outbound_message_inbox": "true", "is_ig_story_mention_enabled:1245_enabled": true, "is_agent_send_broadcast_message_access_enabled": true, "agent_send_broadcast_message_access": "true", "ig_story_mention_enabled:1262": "false", "new_session_webhook_url": "https://xxxxxx", "is_create_tags_enabled": true, "waca_channel": null, "is_enable_leave_agent_enabled": true, "is_bot_enabled": true, "is_agent_takeover_enabled": true, "is_mark_as_resolved_webhook_enabled": true, "user_hide_handover_request_popup_inbox": "false", "is_ig_story_mention_enabled:1263_enabled": true, "is_agent_contact_access_enabled": true, "is_ig_story_mention_enabled:1261_enabled": true, "agent_contact_access": "true", "is_default_properties_created_enabled": true, "is_user_hide_popup_estimation_inbox_enabled": true, "agent_can_add_other_agent": "true", "online_message": "Office hours general", "user_hide_popup_estimation_inbox": "false", "is_api_version_enabled": true, "hide_agent_inbox_customer_id": "false", "enable_leave_agent": "true", "ig_story_mention_enabled:1268": "true", "is_ig_story_mention_enabled:1262_enabled": true, "is_ig_story_mention_enabled:1265_enabled": true, "bot_webhook_url": "https://xxxx", "app_sync_interval": "5000", "is_user_hide_handover_request_popup_inbox_enabled": true, "agent_can_assign_chat": "true", "is_agent_allocation_enabled": true, "is_active": true, "is_enable_rtl_mode_enabled": true, "api_version": "v2", "is_new_session_webhook_enabled": "true", "is_app_sync_interval_enabled": true, "ig_story_mention_enabled:1261": "false", "offline_message": "Outside office hours general", "is_agent_can_assign_chat_enabled": true, "timezone": "+07:00", "allocate_agent_webhook_url": ""https://xxxxxx", "hide_agent_toggle_status": "false", "is_hide_agent_toggle_status_enabled": true, "is_sessional": true, "is_allocate_agent_webhook_enabled": false, "enable_rtl_mode": "false", "is_new_session_webhook_url_enabled": true, "ig_story_mention_enabled:1245": "false", "create_tags": null, "is_agent_can_add_other_agent_enabled": true, "is_is_new_session_webhook_enabled_enabled": true, "mark_as_resolved_webhook_url": "https://xxxxxx" } }, "status": 200}Signature Key
The qiscus-signature-key is a secure mechanism to verify webhook requests. Each webhook payload includes a qiscus-signature-key in the header, generated using HMAC (Hash-based Message Authentication Code). This key combines the webhook's plain text payload with your unique Qiscus Secret Key, ensuring data integrity and authenticity.
How to Verify Webhook Requests
This tutorial shows you how to verify if a webhook request from Qiscus is real using the qiscus-signature-key and HMAC-SHA256. There are many platforms for HMAC. But in this case, we are using Devglan.
- Check your webhook and you can notice
qiscus-signature-keyon the Header.
- Open Devglan as a header verification tools. You will see "Enter Plain Text" and "Enter the Secret Key" fields.
- Go back to your webhook, copy the Raw Content. Then paste it in the Devglan's "Enter Plain Text to Compute Hash" field
- Back to your Omnichannel, click App Information, then copy your Qiscus Secret Key.
- Back to Devglan, paste your Qiscus Secret Key in the "Enter the Secret Key" field
- Make sure SHA-256 is selected as the hash function. Then choose Base64
- Click Compute button to compute the Hashed Output
- Compare the Hashed Output with the
qiscus-signature-keyin your webhook header
If the Hashed Output matches the qiscus-signature-key in the webhook, it means:
The request is valid and really sent by Qiscus.
In other words, the message hasn’t been changed, and it came from Qiscus. This match proves that the webhook payload is authentic and secure.
Was this page helpful?