You can enable webhooks from your Interakt Account’s Developer Settings.
• You will need to provide a Webhook URL & Secret Key for configuring the webhooks for your Interakt account.
Note that you can consume webhooks for:
Delivery statuses (Sent / Delivered / Read / Failed) & Click Status (Quick Reply Button / Call-to-action button) of Templates (HSMs) sent via Interakt’s Template Sending APIs (only available on Growth / Advanced/Enterprise plans)
Delivery statuses (Sent / Delivered / Read / Failed) of Templates (HSMs) sent by setting Campaigns on Interakt (only available on Growth / Advanced/Enterprise plans)
Incoming customer messages on your WhatsApp API number, connected with your Interakt account (only available on Advanced/Enterprise plan)
What kind of webhooks does Interakt provide?
Interakt provides webhooks for the delivery status (sent, delivered, read, failed) of messages sent via Interakt’s API or via Interakt’s campaigns. Interakt also provides button click status for templates sent using Interakt’s Template Send API. Apart from that, Interakt also provides webhooks for incoming customer messages.
What are some important points to note when integrating with webhooks?
-> Check for the type of webhook
For webhooks of templates sent via APIs, the types will be as follows:
“message_api_sent”
“message_api_delivered”
“message_api_read”
“message_api_failed”
“message_api_clicked”
-> For delivery status webhooks of templates sent via Interakt Campaigns, the types will be as follows:
“message_campaign_sent”
“message_campaign_delivered”
“message_campaign_read”
“message_campaign_failed”
-> For incoming customer message webhooks, the type will be as follows:
“message_received”
-> Read the data.customer object to see customer’s phone number & the values of all customer attributes stored in Interakt for that particular customer
-> Read the data.message object to identify which message is being referred to
-> Process the payload and return a success 200 within 3 seconds
(i) Any non-200 status will be considered as failure
(ii) No response within the expected timeout will be considered as a failure
-> For Account Alerts & Events webhooks, the types will be as follows:
“account_alerts”
“account_update”
“account_review_update”
“business_capability_update”
“phone_number_quality_update”
-> For Template Alerts & Events webhooks, the types will be as follows:
“template_performance_metrics”
“message_template_status_update”
“messages”
Webhook Body – message_api_sent:
(note – data sent in the “traits” object depends on the customer traits present in your Interakt account. The traits given in the example below corresponds to a test account)
{
"version": "1.0",
"timestamp": "2022-06-03T05:43:33.237499",
"type": "message_api_sent",
"data": {
"customer": {
"id": "52918eb3-bd00-4331-a51d-c4dcffee48d6",
"channel_phone_number": "917003705584",
"traits": {
"name": "SKGG",
"amount": 7000,
"total_orders_count": 0,
"last_order_id": null,
"last_order_name": null,
"total_spent": "0.00",
"whatsapp_opted_in": false,
"created_at": "2021-06-23T06:46:11",
"User Id": "111",
"email": "[email protected]",
}
},
"message": {
"id": "dfc668a2-c06c-4e9a-a4fd-7b65bc1fdc84",
"chat_message_type": "PublicApiMessage",
"channel_failure_reason": null,
"message_status": "Sent",
"received_at_utc": "2022-06-03T05:43:33.133000",
"delivered_at_utc": null,
"seen_at_utc": null,
"campaign_id": null,
"is_template_message": true,
"raw_template": "{\"id\": \"281a5a78-f2b2-46c9-b9bb-d620d3b2894c\", \"created_at_utc\": \"2022-03-30T07:04:04.078\", \"modified_at_utc\": \"2022-03-31T05:41:09.61\", \"created_by_user_id\": \"37088e03-3633-4aa4-b4d8-99edbc56d4fc\", \"is_deleted\": false, \"name\": \"test_template_lp\", \"language\": \"en\", \"category\": \"ALERT_UPDATE\", \"header_format\": null, \"header\": null, \"header_handle\": null, \"header_handle_file_url\": null, \"header_handle_file_name\": null, \"header_text\": null, \"body\": \"Hi {{1}} \\nWelcome to interakt, my name is {{2}} . I hope your 14 day free trial was helpful. For any queries please reach to us.\", \"body_text\": \"[\\\"Clients\\\", \\\"Sender\\\"]\", \"footer\": \"Team interakt\", \"buttons\": \"[{\\\"type\\\": \\\"QUICK_REPLY\\\", \\\"text\\\": \\\"Thank you\\\"}, {\\\"type\\\": \\\"QUICK_REPLY\\\", \\\"text\\\": \\\"What is qralink?\\\"}, {\\\"type\\\": \\\"QUICK_REPLY\\\", \\\"text\\\": \\\"Speak to an agent\\\"}]\", \"button_text\": null, \"display_name\": \"Test template\", \"organization_id\": \"ba4308f1-a506-44d2-a8c3-17380216cf91\", \"approval_status\": \"APPROVED\", \"wa_template_id\": \"3224400424546364\", \"is_archived\": false}",
"channel_error_code": null,
"message_content_type": "Template",
"media_url": null,
"message": "[{\"type\": \"body\", \"parameters\": [{\"type\": \"text\", \"text\": \"Saandhy\"}, {\"type\": \"text\", \"text\": \"Varun\"}]}]",
"meta_data": {
"source": "PublicInterakt",
"source_data": {
"callback_data": "some text here"
}
}
}
}
}
Webhook Body – message_api_delivered:
(note – data sent in the “traits” object depends on the customer traits present in your Interakt account. The traits given in the example below corresponds to a test account)
{
"version": "1.0",
"timestamp": "2022-06-03T05:43:33.930227",
"type": "message_api_delivered",
"data": {
"customer": {
"id": "52918eb3-bd00-4331-a51d-c4dcffee48d6",
"channel_phone_number": "917003705584",
"traits": {
"name": "SKGG",
"amount": 7000,
"total_orders_count": 0,
"last_order_id": null,
"last_order_name": null,
"total_spent": "0.00",
"whatsapp_opted_in": false,
"created_at": "2021-06-23T06:46:11",
"User Id": "111",
"email": "[email protected]",
}
},
"message": {
"id": "dfc668a2-c06c-4e9a-a4fd-7b65bc1fdc84",
"chat_message_type": "PublicApiMessage",
"channel_failure_reason": null,
"message_status": "Delivered",
"received_at_utc": "2022-06-03T05:43:33.133000",
"delivered_at_utc": "2022-06-03T05:43:33.848000",
"seen_at_utc": null,
"campaign_id": null,
"is_template_message": true,
"raw_template": "{\"id\": \"281a5a78-f2b2-46c9-b9bb-d620d3b2894c\", \"created_at_utc\": \"2022-03-30T07:04:04.078\", \"modified_at_utc\": \"2022-03-31T05:41:09.61\", \"created_by_user_id\": \"37088e03-3633-4aa4-b4d8-99edbc56d4fc\", \"is_deleted\": false, \"name\": \"test_template_lp\", \"language\": \"en\", \"category\": \"ALERT_UPDATE\", \"header_format\": null, \"header\": null, \"header_handle\": null, \"header_handle_file_url\": null, \"header_handle_file_name\": null, \"header_text\": null, \"body\": \"Hi {{1}} \\nWelcome to interakt, my name is {{2}} . I hope your 14 day free trial was helpful. For any queries please reach to us.\", \"body_text\": \"[\\\"Clients\\\", \\\"Sender\\\"]\", \"footer\": \"Team interakt\", \"buttons\": \"[{\\\"type\\\": \\\"QUICK_REPLY\\\", \\\"text\\\": \\\"Thank you\\\"}, {\\\"type\\\": \\\"QUICK_REPLY\\\", \\\"text\\\": \\\"What is qralink?\\\"}, {\\\"type\\\": \\\"QUICK_REPLY\\\", \\\"text\\\": \\\"Speak to an agent\\\"}]\", \"button_text\": null, \"display_name\": \"Test template\", \"organization_id\": \"ba4308f1-a506-44d2-a8c3-17380216cf91\", \"approval_status\": \"APPROVED\", \"wa_template_id\": \"3224400424546364\", \"is_archived\": false}",
"channel_error_code": null,
"message_content_type": "Template",
"media_url": null,
"message": "[{\"type\": \"body\", \"parameters\": [{\"type\": \"text\", \"text\": \"Saandhy\"}, {\"type\": \"text\", \"text\": \"Varun\"}]}]",
"meta_data": {
"source": "PublicInterakt",
"source_data": {
"callback_data": "some text here"
}
}
}
}
}
Webhook Body – message_api_read:
(note – data sent in the “traits” object depends on the customer traits present in your Interakt account. The traits given in the example below corresponds to a test account)
{
"version": "1.0",
"timestamp": "2022-06-03T05:43:33.930227",
"type": "message_api_read",
"data": {
"customer": {
"id": "52918eb3-bd00-4331-a51d-c4dcffee48d6",
"channel_phone_number": "917003705584",
"traits": {
"name": "SKGG",
"amount": 7000,
"total_orders_count": 0,
"last_order_id": null,
"last_order_name": null,
"total_spent": "0.00",
"whatsapp_opted_in": false,
"created_at": "2021-06-23T06:46:11",
"User Id": "111",
"email": "[email protected]",
}
},
"message": {
"id": "dfc668a2-c06c-4e9a-a4fd-7b65bc1fdc84",
"chat_message_type": "PublicApiMessage",
"channel_failure_reason": null,
"message_status": "Read",
"received_at_utc": "2022-06-03T05:43:33.133000",
"delivered_at_utc": "2022-06-03T05:43:33.848000",
"seen_at_utc": "2022-06-03T05:43:34.257000",
"campaign_id": null,
"is_template_message": true,
"raw_template": "{\"id\": \"281a5a78-f2b2-46c9-b9bb-d620d3b2894c\", \"created_at_utc\": \"2022-03-30T07:04:04.078\", \"modified_at_utc\": \"2022-03-31T05:41:09.61\", \"created_by_user_id\": \"37088e03-3633-4aa4-b4d8-99edbc56d4fc\", \"is_deleted\": false, \"name\": \"test_template_lp\", \"language\": \"en\", \"category\": \"ALERT_UPDATE\", \"header_format\": null, \"header\": null, \"header_handle\": null, \"header_handle_file_url\": null, \"header_handle_file_name\": null, \"header_text\": null, \"body\": \"Hi {{1}} \\nWelcome to interakt, my name is {{2}} . I hope your 14 day free trial was helpful. For any queries please reach to us.\", \"body_text\": \"[\\\"Clients\\\", \\\"Sender\\\"]\", \"footer\": \"Team interakt\", \"buttons\": \"[{\\\"type\\\": \\\"QUICK_REPLY\\\", \\\"text\\\": \\\"Thank you\\\"}, {\\\"type\\\": \\\"QUICK_REPLY\\\", \\\"text\\\": \\\"What is qralink?\\\"}, {\\\"type\\\": \\\"QUICK_REPLY\\\", \\\"text\\\": \\\"Speak to an agent\\\"}]\", \"button_text\": null, \"display_name\": \"Test template\", \"organization_id\": \"ba4308f1-a506-44d2-a8c3-17380216cf91\", \"approval_status\": \"APPROVED\", \"wa_template_id\": \"3224400424546364\", \"is_archived\": false}",
"channel_error_code": null,
"message_content_type": "Template",
"media_url": null,
"message": "[{\"type\": \"body\", \"parameters\": [{\"type\": \"text\", \"text\": \"Saandhy\"}, {\"type\": \"text\", \"text\": \"Varun\"}]}]",
"meta_data": {
"source": "PublicInterakt",
"source_data": {
"callback_data": "some text here"
}
}
}
}
Webhook Body – message_api_failed:
(note – data sent in the “traits” object depends on the customer traits present in your Interakt account. The traits given in the example below corresponds to a test account)
{
"version": "1.0",
"timestamp": "2022-06-03T05:56:10.699936",
"type": "message_api_failed",
"data": {
"customer": {
"id": "82a5b5bc-5509-4225-a9e9-bbe4c150516b",
"channel_phone_number": "919831",
"traits": {
"name": "",
"whatsapp_opted_in": true
}
},
"message": {
"id": "80b4b1f1-dc39-46dc-a133-bf09a12c3d4e",
"chat_message_type": "PublicApiMessage",
"channel_failure_reason": "Recipient is not a valid WhatsApp user",
"message_status": "Failed",
"received_at_utc": "2022-06-03T05:56:10.502000",
"delivered_at_utc": null,
"seen_at_utc": null,
"campaign_id": null,
"is_template_message": true,
"raw_template": "{\"id\": \"281a5a78-f2b2-46c9-b9bb-d620d3b2894c\", \"created_at_utc\": \"2022-03-30T07:04:04.078\", \"modified_at_utc\": \"2022-03-31T05:41:09.61\", \"created_by_user_id\": \"37088e03-3633-4aa4-b4d8-99edbc56d4fc\", \"is_deleted\": false, \"name\": \"test_template_lp\", \"language\": \"en\", \"category\": \"ALERT_UPDATE\", \"header_format\": null, \"header\": null, \"header_handle\": null, \"header_handle_file_url\": null, \"header_handle_file_name\": null, \"header_text\": null, \"body\": \"Hi {{1}} \\nWelcome to interakt, my name is {{2}} . I hope your 14 day free trial was helpful. For any queries please reach to us.\", \"body_text\": \"[\\\"Clients\\\", \\\"Sender\\\"]\", \"footer\": \"Team interakt\", \"buttons\": \"[{\\\"type\\\": \\\"QUICK_REPLY\\\", \\\"text\\\": \\\"Thank you\\\"}, {\\\"type\\\": \\\"QUICK_REPLY\\\", \\\"text\\\": \\\"What is qralink?\\\"}, {\\\"type\\\": \\\"QUICK_REPLY\\\", \\\"text\\\": \\\"Speak to an agent\\\"}]\", \"button_text\": null, \"display_name\": \"Test template\", \"organization_id\": \"ba4308f1-a506-44d2-a8c3-17380216cf91\", \"approval_status\": \"APPROVED\", \"wa_template_id\": \"3224400424546364\", \"is_archived\": false}",
"channel_error_code": "1013",
"message_content_type": "Template",
"media_url": null,
"message": "[{\"type\": \"body\", \"parameters\": [{\"type\": \"text\", \"text\": \"Saandhy\"}, {\"type\": \"text\", \"text\": \"Varun\"}]}]",
"meta_data": {
"source": "PublicInterakt",
"source_data": {
"callback_data": "some text here"
}
}
}
}
}
Webhook Body – message_api_clicked(Quick Reply Buttons):
{
"version": "1.0",
"timestamp": "2024-06-10T08:38:08.837610",
"type": "message_api_clicked",
"data": {
"customer": {
"id": "fe366bc2-14df-40f3-ab56-20f67f5c6694",
"channel_phone_number": "917003705584",
"phone_number": "7003705584",
"country_code": "+91",
"traits": {
"name": "Saandhy Ganeriwala",
"whatsapp_opted_in": true}
},
"message": {
"id": "f6f22110-9eab-4282-9b2c-673c3bbaa0fa",
"chat_message_type": "PublicApiMessage",
"channel_failure_reason": null,
"message_status": "Read",
"received_at_utc": "2024-06-10T08:37:46.309000",
"delivered_at_utc": "2024-06-10T08:37:48.149000",
"seen_at_utc": "2024-06-10T08:38:05.643000",
"campaign_id": null,
"is_template_message": true,
"raw_template": "{\"id\": \"8472d21c-7d9d-40d4-9d36-2616c67a39bd\", \"created_at_utc\": \"2024-02-22T11:46:07.328\", \"modified_at_utc\": \"2024-06-06T15:40:29.987\", \"created_by_user_id\": \"None\", \"is_deleted\": false, \"name\": \"looking_for_feedback_23\", \"language\": \"en\", \"category\": \"UTILITY\", \"sub_category\": null, \"template_category_label\": null, \"header_format\": null, \"header\": null, \"header_handle\": null, \"header_handle_file_url\": null, \"header_handle_file_name\": null, \"header_text\": null, \"body\": \"Hey {{1}} \\n\\nThis is {{2}} from Interakt's Product Team. We are looking to improve our product so that businesses like yours can use & derive more value from Interakt.\\n\\nWe hence have a very simple question for you - *What can we do to make Interakt more useful for you?*\\n\\nYou can fill the feedback form, or, schedule a 30 mins meeting with me.\", \"body_text\": \"[\\n \\\"John\\\",\\n \\\"Mark\\\"\\n]\", \"footer\": null, \"buttons\": \"[{\\\"type\\\": \\\"QUICK_REPLY\\\", \\\"text\\\": \\\"Fill Feedback Form\\\"}, {\\\"type\\\": \\\"QUICK_REPLY\\\", \\\"text\\\": \\\"Schedule Meet\\\"}]\", \"button_text\": null, \"allow_category_change\": true, \"limited_time_offer\": null, \"autosubmitted_for\": null, \"display_name\": \"looking_for_feedback_23\", \"organization_id\": \"80a1681a-3fbd-4580-beff-eb93478211a5\", \"approval_status\": \"APPROVED\", \"wa_template_id\": \"1586626795428976\", \"is_archived\": false, \"channel_type\": \"Whatsapp\", \"is_click_tracking_enabled\": false, \"allow_delete\": true, \"rejection_reason\": null, \"carousel_cards\": \"[]\", \"is_carousel\": false, \"is_mpm\": false}",
"channel_error_code": null,
"message_content_type": "Template",
"media_url": null,
"message": "[{\"type\": \"body\", \"parameters\": [{\"type\": \"text\", \"text\": \"body_variable_value_1\"}, {\"type\": \"text\", \"text\": \"body_variable_value_2\"}]}]",
"meta_data": {
"source": "PublicInterakt",
"source_data": {
"callback_data": "some text here123"
},
"message_cost": {
"whatsapp_cost": "0.03",
"interakt_markup": "0.3",
"actual_message_cost": "0.33"
}
"click_type": "QR",
"button_text": "Fill Feedback Form",
"button_link": "",
"click_timestamp": "2024-06-10 08:38:08.635664",
"button_payload": {
"payload": {
"type": "QUICK_REPLY",
"text": "Fill Feedback Form"
}
}
}
}
Webhook Body – message_api_clicked(Call-to-action Buttons):
{
"customer": { "id": "fe366bc2-14df-40f3-ab56-20f67f5c6694", "channel_phone_number": "917003705584", "phone_number": "7003705584", "country_code": "+91", "traits": { "name": "Saandhy Ganeriwala", "email": "[email protected]", "whatsapp_opted_in": true } }, "message": { "id": "c2e35816-f6cb-4893-8cd5-99d2f6060535", "chat_message_type": "PublicApiMessage", "channel_failure_reason": null, "message_status": "Read", "received_at_utc": "2024-06-10T08:47:19.352000", "delivered_at_utc": "2024-06-10T08:47:21.123000", "seen_at_utc": "2024-06-10T08:47:21.723000", "campaign_id": null, "is_template_message": true, "raw_template": "{\"id\": \"fe9066ad-57a2-4137-ad5d-292b08be1551\", \"created_at_utc\": \"2022-06-09T08:00:26.058\", \"modified_at_utc\": \"2024-06-10T08:46:06.076\", \"created_by_user_id\": \"2f0a1016-0886-4dfb-8681-4c3aed78df8e\", \"is_deleted\": false, \"name\": \"order_shipped_1010123\", \"language\": \"en\", \"category\": \"UTILITY\", \"header_format\": null, \"header\": null, \"header_handle\": null, \"header_handle_file_url\": null, \"header_handle_file_name\": null, \"header_text\": null, \"body\": \"Hi {{1}}, your order is shipped. Please click below to track the order.\", \"body_text\": \"[\\n \\\"John\\\"\\n]\", \"footer\": null, \"buttons\": \"[{\\\"type\\\":\\\"URL\\\",\\\"text\\\":\\\"Track Order\\\",\\\"url\\\":\\\"https://www.interakt.shop/\\\"}]\", \"button_text\": \"[]\", \"display_name\": \"Order Shipped 1010123\", \"organization_id\": \"80a1681a-3fbd-4580-beff-eb93478211a5\", \"approval_status\": \"APPROVED\", \"wa_template_id\": \"8276292472397006\", \"is_archived\": false, \"template_category_label\": null, \"channel_type\": \"Whatsapp\", \"allow_delete\": true, \"allow_category_change\": true, \"autosubmitted_for\": null, \"rejection_reason\": null, \"is_click_tracking_enabled\": true, \"limited_time_offer\": null, \"sub_category\": null, \"carousel_cards\": \"[]\", \"is_carousel\": false, \"is_mpm\": false}", "channel_error_code": null, "message_content_type": "Template", "media_url": null, "message": "[{\"type\": \"body\", \"parameters\": [{\"type\": \"text\", \"text\": \"body_variable_value_1\"}]}, {\"type\": \"button\", \"sub_type\": \"url\", \"index\": 0, \"parameters\": [{\"type\": \"text\", \"text\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcmdfaWQiOiI4MGExNjgxYS0zZmJkLTQ1ODAtYmVmZi1lYjkzNDc4MjExYTUiLCJjYW1wYWlnbl9pZCI6IiIsImNhbXBhaWduX3RyYWNraW5nX2VuYWJsZWQiOmZhbHNlLCJ0ZW1wbGF0ZV9pZCI6ImZlOTA2NmFkLTU3YTItNDEzNy1hZDVkLTI5MmIwOGJlMTU1MSIsInBob25lIjoiOTE3MDAzNzA1NTg0IiwiY2xpY2tfdHlwZSI6IkNUQSIsImxpbmsiOiJodHRwczovL3d3dy5pbnRlcmFrdC5zaG9wLyIsImJ1dHRvbl90ZXh0IjoiVHJhY2sgT3JkZXIiLCJyYW5kb21faWQiOiIyZGYzNWFjMS04OGVjLTQ1ODItYjAyNy1lZDIzNTEwYzA2NDEiLCJleHBpcnlfZGF0ZSI6IjIwMjQtMDctMTAgMDg6NDc6MDguNzMwNzY5IiwibWV0YWRhdGEiOnsic291cmNlIjoiUHVibGljSW50ZXJha3QiLCJzb3VyY2VfZGF0YSI6eyJjYWxsYmFja19kYXRhIjoic29tZSB0ZXh0IGhlcmUxMjMifX0sInBhcmVudF9tZXNzYWdlX2lkIjoiYzJlMzU4MTYtZjZjYi00ODkzLThjZDUtOTlkMmY2MDYwNTM1IiwiaXNfcHVibGljX2FwaV9tZXNzYWdlIjp0cnVlfQ.GJTt0CXc9BeYOHhXJvk9XSy9Pk5bK36q9jVMeeVeBCM\"}]}]", "meta_data": { "source": "PublicInterakt", "source_data": { "callback_data": "some text here123" }, "message_cost": { "whatsapp_cost": "0.03", "interakt_markup": "0.3", "actual_message_cost": "0.33" } } }, "event": { "callbackData": "some text here123", "click_type": "CTA", "button_text": "Track Order", "button_link": "https://www.interakt.shop/", "click_timestamp": "2024-06-10 08:47:26.948896" } }
Webhook Body – message_received:
(note – data sent in the “traits” object depends on the customer traits present in your Interakt account. The traits given in the example below corresponds to a test account)
{
"version": "1.0",
"timestamp": "2022-06-03T05:57:57.496889",
"type": "message_received",
"data": {
"customer": {
"id": "52918eb3-bd00-4331-a51d-c4dcffee48d6",
"channel_phone_number": "917003705584",
"traits": {
"name": "SKGG",
"amount": 7000,
"total_orders_count": 0,
"last_order_id": null,
"last_order_name": null,
"total_spent": "0.00",
"whatsapp_opted_in": false,
"created_at": "2021-06-23T06:46:11",
"User Id": "111",
"email": "[email protected]",
}
},
"message": {
"id": "60076f05-da52-4dd1-b813-36223c1eded7",
"chat_message_type": "CustomerMessage",
"channel_failure_reason": null,
"message_status": "Sent",
"received_at_utc": "2022-06-03T05:57:57.359000",
"delivered_at_utc": null,
"seen_at_utc": null,
"campaign_id": null,
"is_template_message": false,
"raw_template": null,
"channel_error_code": null,
"message_content_type": "Text",
"media_url": null,
"message": "Thank you",
"meta_data": {}
}
}
}
Webhook Body – account_alerts:
“version”: “1.0”,
“timestamp”: “2022-06-03T05:43:33.930227”,
"type": "account_alerts",
}
Webhook Body – account_update:
{
“version”: “1.0”,
“timestamp”: “2022-06-03T05:43:33.930227”,
"field": "account_update",
"data": {
"phone_number": "16505551111",
"event": "VERIFIED_ACCOUNT"
}
}
Webhook Body – account_review_update:
{
“version”: “1.0”,
“timestamp”: “2022-06-03T05:43:33.930227”,
"type": "account_review_update",
"data": {
"decision": "APPROVED"
}
}
Webhook Body – business_capability_update:
{
“version”: “1.0”,
“timestamp”: “2022-06-03T05:43:33.930227”,
"type": "business_capability_update",
"data": {
"max_daily_conversation_per_phone": 123,
"max_phone_numbers_per_waba": 23,
"max_phone_numbers_per_business": 120
}
}
Webhook Body – phone_number_quality_update:
{
“version”: “1.0”,
“timestamp”: “2022-06-03T05:43:33.930227”,
"type": "phone_number_quality_update",
"data": {
"display_phone_number": "16505551111",
"event": "FLAGGED",
"current_limit": "TIER_10K"
}
}
Webhook Body – template_performance_metrics:
{
“version”: “1.0”,
“timestamp”: “2022-06-03T05:43:33.930227”,
"type": "template_performance_metrics",
"data": {
"templates_performance_metrics": {
“template_id”: “”,
“template_name”: “”,
“template_language”: “”,
}
}
}
Webhook Body – message_template_status_update:
{
“version”: “1.0”,
“timestamp”: “2022-06-03T05:43:33.930227”,
"type": "message_template_status_update",
"data": {
"event": "APPROVED",
"message_template_id": 12345678,
"message_template_name": "my_message_template",
"message_template_language": "pt-BR",
"reason": null
}
}
Webhook Body – messages:
{
“version”: “1.0”,
“timestamp”: “2022-06-03T05:43:33.930227”,
"type": "messages",
}
Webhook Body – workflow_response_update:
(Note – The workflow webhook does not follow the same pattern as other webhooks with customer and message objects, it only sends the data object with the customer identifier and workflow responses )
The workflow webhook will be triggered at each step. However, if the customer replies to the 1st step, then a webhook will be triggered with only 1 question and response in data field. Then the customer replies to 2nd step, another webhook will be triggered which have 2 questions and 2 answer in the data field. Which means 1st and 2nd too. Developer will have to ensure they don’t duplicate the messages.
For incoming workflow update webhooks, the type will be as follows:
- “workflow_response_update”
{
"version": "1.0",
"timestamp": "2023-08-25T04:35:59.841972",
"type": "workflow_response_update",
"data": {
"id": "66044dd4-d0b8-4efd-9c55-a970347f90f1",
"created_at_utc": "2023-08-25T04:35:27.341000",
"modified_at_utc": "2023-08-25T04:35:59.462000",
"workflow_id": "d2a02d35-6cba-4873-a1fd-060de0342cdd",
"customer_id": "13212830-0a1b-473f-b05a-ddd6872d367b",
"customer_name": "Customer Name",
"customer_number": "+919999999999",
"data": [
{
"question": {
"id": "95a68fb7-0d52-4597-a5ef-0494f0c49509",
"created_at_utc": "2023-08-25T04:35:27.949000",
"step_number": 1,
"message": "What is your company size?",
"message_type": "List Message",
"buttons": [],
"list_message_name": "interaktive_list",
"user_trait_name": "company_size",
"variable_fallback_values": []
},
"answer": {
"id": "f37b61e7-065e-413f-bc36-bf0ba183e605",
"created_at_utc": "2023-08-25T04:35:38.351000",
"message": "500+",
"media_id": null,
"media_url": null,
"media_file_name": null,
"received_at_utc": "2023-08-25T04:35:36.776000",
"message_content_type": "InteractiveListReply"
}
},
{
"question": {
"id": "e3375b79-86ea-454d-a9eb-9b4154020f56",
"created_at_utc": "2023-08-25T04:35:39.478000",
"step_number": 2,
"message": "Great, would you like to continue?",
"message_type": "Normal Message",
"buttons": [],
"list_message_name": "",
"user_trait_name": null,
"variable_fallback_values": [
]
},
"answer": {
"id": "d9afabb4-1411-4010-b21b-4f51c311850b",
"created_at_utc": "2023-08-25T04:35:59.222000",
"message": "Yes",
"media_id": null,
"media_url": null,
"media_file_name": null,
"received_at_utc": "2023-08-25T04:35:57.611000",
"message_content_type": "Text"
}
}
],
"triggered_from": "FAQ Message"
}
}
| Field | Description | |
|---|---|---|
Webhook Requirements
Your webhook should meet the following minimum performance requirements
- Must be an HTTPS endpoint
- Respond to all webhook events with a 200 OK
- Respond to all webhook events in 3 seconds or less
Interakt Security Requirements
The HTTP request will contain an “Interakt-Signature” header which contains the Hex encoded SHA256 signature of the request payload computed using the HMAC algorithm and the secret_key shared in advance, and prefixed with sha256=.
Your callback endpoint should verify this signature to validate the integrity and origin of the payload.
For Eg: Sample Headers Received in Webhook:
Interakt-Signature:sha256=b84783d10ede5bd6ed771e8b16fbe5a7093340159d6e49ec4248350b6ec2c7b4
If your Payload is:
‘{“foo”:1,”bar”:2}’
And your Secret key is = examplekey
Sample Code given in Python and Node JS for your reference to verify webhooks
Sample Code For Verifying Webhooks
Python:
import hmac
from hashlib import sha256
from typing import Union
def generate_signature(secret_key: str, payload: Union[bytes, str]):
“””Generates SHA256 signature prepended with sha256=
Args:
secret_key [String] -> shared secret, known by your service
payload [String or bytes] -> received in request body (stringified JSON)
“””
if not payload:
payload = None
elif isinstance(payload, str):
payload = payload.encode(“utf-8”)
hash_value = hmac.new(secret_key.encode(“utf-8”), payload, sha256).hexdigest()
return “sha256=” + str(hash_value)
def verify_signature(secret_key: str, payload: Union[bytes, str], signature: str):
“””Verifies SHA256 signature prepended with sha256=
Args:
secret_key [String] -> shared secret, known by your service
payload [String or bytes] -> received in request body (stringified JSON)
signature [Signature] -> received in Interakt-Signature request header
“””
sha256_signature = generate_signature(secret_key=secret_key, payload=payload)
return sha256_signature == signature
# test the function
received_hmac = “sha256=b84783d10ede5bd6ed771e8b16fbe5a7093340159d6e49ec4248350b6ec2c7b4”
data_string = ‘{“foo”:1,”bar”:2}’
key = “examplekey”
if verify_signature(secret_key=key, payload=data_string, signature=received_hmac):
print(“Signature valid”)
else:
print(“Signature Invalid”)
Node JS:
We Can use crypto-js NPM Package
Ref: https://www.npmjs.com/package/crypto-js
const CryptoJS = require(‘crypto-js’);
function verifyHmac(
receivedHmac, // received in Interakt-Signature request header
dataString, // received in request body (stringified JSON)
key // shared secret, known by your service
) {
const generatedHmac = CryptoJS.HmacSHA256(dataString, key);
const generatedHmacBase64 = “sha256=” + CryptoJS.enc.Hex.stringify(generatedHmac);
return generatedHmacBase64 === receivedHmac;
}
// test the function
const receivedHmac = “sha256=b84783d10ede5bd6ed771e8b16fbe5a7093340159d6e49ec4248350b6ec2c7b4”;
const dataString = ‘{“foo”:1,”bar”:2}’;
const key = “examplekey”;
if (verifyHmac(receivedHmac, dataString, key)) {
console.log(“Signature Valid”);
} else {
console.log(“Signature Invalid”);
}
C#:
using System;
using System.Text;
using System.Security.Cryptography;
class Program
{
public static string ComputeHash(string secret, string payload)
{
byte[] bytes = Encoding.UTF8.GetBytes(secret);
HMAC hmac = new HMACSHA256(bytes);
bytes = Encoding.UTF8.GetBytes(payload);
return “sha256=” + BitConverter.ToString(hmac.ComputeHash(bytes)).Replace(“-“, “”).ToLower();
}
public static bool HashIsValid(string secret, string payload, string verify)
{
string hashString = ComputeHash(secret, payload);
return verify == hashString;
}
static void Main(string[] args)
{
// Testing our code
string receivedHmac = “sha256=b84783d10ede5bd6ed771e8b16fbe5a7093340159d6e49ec4248350b6ec2c7b4”;
string dataString = “{\”foo\”:1,\”bar\”:2}”;
string key = “examplekey”;
Console.WriteLine(HashIsValid(key, dataString, receivedHmac));
}
}
PHP:
<?php
$secret = “examplekey”;// your secret key
if (isset($_POST)) {
$payload = file_get_contents(‘php://input’);
$headers = getallheaders();
if (array_key_exists(“Interakt-Signature”, $headers)) {
$signature = $headers[“Interakt-Signature”];
$result = hash_is_valid($secret, $payload, $signature);
// if $result is true
// Hash is valid Api call is coming from interak
}
header(“HTTP/1.1 200 OK”);
}
function compute_hash($secret, $payload)
{
$prefix = “sha256=”;
$hexHash = hash_hmac(‘sha256’, $payload, utf8_encode($secret));
return $prefix.$hexHash;
}
function hash_is_valid($secret, $payload, $verify)
{
$computed_hash = compute_hash($secret, $payload);
return hash_equals($verify,$computed_hash);
}
?>
You can test your Endpoint Using Postman with a pre-request script:
var CryptoJS = require(“crypto-js”);
var keyString = ‘examplekey’;
function encrypt(data) {
var val = CryptoJS.HmacSHA256(data, keyString);
return “sha256=” + CryptoJS.enc.Hex.stringify(val);
}
// Set environment variables to postman
pm.environment.set(
“hmac_sign”, encrypt(request.data)
);
This code will take your request body, create a HMAC signature using key “examplekey” (mentioned in line 2 of code) and set the env hmac_sign
Here is a Sample curl which is sending “Interakt-Signature” in headers
curl –location –request POST ‘<YOUR_ENDPOINT_HERE>’ \
–header ‘Interakt-Signature: {{hmac_sign}}’ \
–header ‘Content-Type: application/json’ \
–data-raw ‘{“foo”:1,”bar”:2}’
Instead of ‘{“foo”:1,”bar”:2}’ test with any request body.
Refer Screenshots :
