# Webhooks ### Bot Webhook This Webhook will be triggered when your customer sends a message to your Qiscus Omnichannel Chat. ```http { "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. ```http { "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. ```http { "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 :** ```http [POST] https://omnichannel.qiscus.com/api/v1/app/webhook/mark_as_resolved ``` Please follow this [page](https://documentation.qiscus.com/omnichannel-chat/authentication#login) to get your AdminToken **CURL Sample:** ```http 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:** ```http { "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:** ```http { "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:** ```json 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](https://documentation.qiscus.com/omnichannel-chat/authentication#rest-token) to get Qiscus App ID and Qiscus Secret Key. **Sample Response:** ```http { "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. ```http { "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 :** ```http [POST] {{BaseUrl}}/api/v2/app/config/auth_webhook ``` **CURL Sample:** ```http curl --location -g --request POST '{{BaseUrl}}/api/v2/app/config/auth_webhook' \ --header 'Authorization: {{AdminToken}}' \ --form 'enabled=""' \ --form 'url=""' ``` Please follow this [page](https://documentation.qiscus.com/omnichannel-chat/authentication#login) to get your AdminToken. **Sample Response:** ```http { "data": { "configs": { "auth_webhook_url": "https://webhook.site/xxxxxxxxxxxx", "is_auth_webhook_enabled": "true" } }, "status": 200 } ``` **Sample payload:** **Admin** ```json { "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** ```json { "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** ```json { "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. ```json 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:** ```http { "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](https://www.devglan.com/online-tools/hmac-sha256-online). 1. Check your webhook and you can notice `qiscus-signature-key`on the Header. ![](https://uploads.developerhub.io/prod/joxo/liof6xoqbkn9dx2cnx8iurxm595h6loz11qtq5bbymw0vsxo2az8uwv69zv0qxja.png) 2. Open Devglan as a header verification tools. You will see "Enter Plain Text" and "Enter the Secret Key" fields. 3. Go back to your webhook, copy the Raw Content. Then paste it in the Devglan's "Enter Plain Text to Compute Hash" field ![](https://uploads.developerhub.io/prod/joxo/nvxkf54rahzm9df9ufz62tb7m2zdrhdwxuzdsao7s3skp91fdi3mb3ut4silb424.png) 4. Back to your Omnichannel, click App Information, then copy your Qiscus Secret Key. ![](https://uploads.developerhub.io/prod/joxo/ze5g761k5317z3r8kxi5shqepkvav0gxiu9v8l1o5vv0zudxn2dy5nxglkqicibx.png) 5. Back to Devglan, paste your Qiscus Secret Key in the "Enter the Secret Key" field 6. Make sure **SHA-256** is selected as the hash function. Then choose **Base64** 7. Click Compute button to compute the Hashed Output ![](https://uploads.developerhub.io/prod/joxo/oytu93j3hijurzgyv0jbqwhf3g079ni0fx94mtd8m344x544rw6d5ga3tt9tccqe.png) 8. Compare the Hashed Output with the `qiscus-signature-key` in your webhook header ![](https://uploads.developerhub.io/prod/joxo/bxmppfsp9rq4kj0etxjm6x5k9ag9oer9377bq051b2vfdda2w377lmfjg815wsvn.png) > **Info** > > 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**. --- [All pages in this documentation](https://documentation.qiscus.com/llms.txt)