Webhooks

You can connect webhooks to receive notifications to your handler when subscribers interact with your chatbot.

Global webhooks

These webhooks are sent when the tracked event occurs. You can track the following events:

Bot subscription Gets sent whenever a user subscribes to your chatbot and includes new subscriber data.
Incoming messages Gets sent whenever you receive new incoming messages and includes data about the sender and their message text.
Outbound messages Gets sent whenever you send new messages and includes data about the receiver and your message text.
Opened live chat Gets sent whenever a user reaches the Action element with the Open chat option.
Launched custom trigger flow Gets sent whenever your flow is triggered and includes user and flow data.
Redirect Gets sent whenever a user clicks through a button link and includes link, sending element, and user data.
Bot unsubscribe Gets sent whenever a user unsubscribes from your bot and includes user and bot data.
Bot blocked Gets sent whenever a user blocks bot messages and includes user and bot data.

Connecting webhooks

Go to Bot Settings > Webhooks. Enter the URL to which you want to send data, and select the events you want to track.

Learn more: How to enable global webhooks.

Webhook structure

Webhooks can pass the following data:

Parameter Type Description
info string Data from the messaging platform or communication channel.
service string Messaging platform or communication channel type. It can take the following values based on where your bot is connected: messenger (Facebook Messenger), telegram, viber, instagram, and livechat.
title string Webhook name. It can take the following values based on your tracked event: new_subscriber, run_custom_flow, open_chat, link_click, bot_block, unsubscribe, outgoing_message, and incoming_message.

If you create your own webhook in the Action element, it will have the name you add.
bot object Chatbot data
url string Link to the bot page
external_id int Facebook Page ID;

Instagram or WhatsApp business account ID;

Telegram or Viber bot ID.
id objectID string SendPulse bot ID.
name string Your bot’s name
contact object Contact data
<your_variable_name> <your_variable_type> Variable name in which the value is passed as:

"variable_name": "value"
email string Contact email address
phone string Contact phone number
last_message string Last message from the contact. A Telegram message can include up to 2,000 characters, and messages from other social media can include up to 512 characters.
photo string Link to the contact’s social media profile picture
tags array Assigned tag as:

["tag1", "tag2"]
id string SendPulse contact ID
name string Contact name
operator object Assignee for chat with a contact
date int Webhook trigger date and time in milliseconds

Webhook example for the Bot subscription event:

[
   {
      "info":null,
      "service":"telegram",
      "title":"new_subscriber",
      "bot":{
         "url":"https://t.me/best_bot",
         "external_id":1845120800,
         "id":"60b0a854b4d8073f592b92f3",
         "name":"BEST"
      },
      "contact":{
         "username":"veronica",
         "name":"name",
         "tags":[
            
         ],
         "last_message":"Test",
         "photo":null,
         "variables":{
            "name":"Veronica Petrova",
            "Phone":"380985236985",
            "Email":"test@gmail.com"
         },
         "operator":{
            "username":"test dza",
            "created_at":1723636543,
            "user_id":8356384,
            "avatar":null,
            "email":"custombot1@e.cn.ua"
         },
         "id":"60b0a854083b4964fd0f7b657847848"
      },
      "date":16377590567070
   }
]

Webhook example for the Opened live chat event:

[
   {
      "info":null,
      "service":"telegram",
      "title":"open_chat",
      "bot":{
         "url":"https://t.me/best_bot",
         "external_id":18451208007356,
         "id":"60b0a854b4d8073f592b92f673563",
         "name":"BEST"
      },
      "contact":{
         "username":"veronica",
         "name":"veronica",
         "tags":[
            
         ],
         "last_message":"Test",
         "photo":null,
         "variables":{
            "name":"Veronica Petrova",
            "Phone":"380985236985",         
            "Email":"test@gmail.com"
         },
         "operator":{
            "username":"test dza",
            "created_at":1723636543,
            "user_id":8356384,
            "avatar":null,
            "email":"custombot1@e.cn.ua"
         },
         "id":"60b0a854083b4964fd0f756756b65"
      },
      "date":16377587917546
   }
]

Webhook example for the Launched custom trigger flow event:

[
   {
      "info":null,
      "service":"telegram",
      "title":"run_custom_flow",
      "bot":{
         "url":"https://t.me/best_bot",
         "external_id":1845120856756700,
         "id":"60b0a854b4d8073f592b92f3564567",
         "name":"BEST"
      },
      "contact":{
         "username":"veronica",
         "name":"veronica",
         "tags":[
            
         ],
         "last_message":"Test",
         "photo":null,
         "variables":{
            "name":"Veronica Petrova",
            "Phone":"380985236985",         
            "Email":"test@gmail.com"
         },
         "operator":{
            "username":"test dza",
            "created_at":1723636543,
            "user_id":8356384,
            "avatar":null,
            "email":"custombot1@e.cn.ua"
         },
         "id":"60b0a854083b4964fd0f7b655858"
      },
      "date":163775889778478
   }
]

Webhook example for the Redirect event:

[
   {
      "info":null,
      "service":"telegram",
      "title":"link_click",
      "bot":{
         "url":"https://t.me/best_bot",
         "external_id":1845120806750,
         "id":"60b0a854b4d8073f592b9254677654f3",
         "name":"BEST"
      },
      "contact":{
         "username":"veronica",
         "name":"veronica",
         "tags":[
            
         ],
         "last_message":"Test",
         "photo":null,
         "variables":{
            "name":"Veronica Petrova",
            "Phone":"380985236985",         
            "Email":"test@gmail.com"
         },
          "operator":{
            "username":"test dza",
            "created_at":1723636543,
            "user_id":8356384,
            "avatar":null,
            "email":"custombot1@e.cn.ua"
         },
         "id":"60b0a854083b4964fd0f65757b65"
      },
      "date":16377589785675
   }
]

Webhook example for the Bot unsubscribe event:

[
   {
      "info":null,
      "service":"telegram",
      "title":"unsubscribe",
      "bot":{
         "url":"https://t.me/best_bot",
         "external_id":1845120806780,
         "id":"60b0a854b4d8073f592b92678f3",
         "name":"BEST"
      },
      "contact":{
         "username":"veronica",
         "name":"veronica",
         "tags":[
            
         ],
         "last_message":"Test",
         "photo":null,
         "variables":{
            "name":"Veronica Petrova",
            "Phone":"380985236985",         
            "Email":"test@gmail.com"
         },
         "operator":{
            "username":"test dza",
            "created_at":1723636543,
            "user_id":8356384,
            "avatar":null,
            "email":"custombot1@e.cn.ua"
         },
         "id":"60b0a854083b4966784fd0f7b65"
      },
      "date":1637759687101
   }
]

Webhook example for the Bot blocked event:

[
   {
      "info":null,
      "service":"telegram",
      "title":"bot_block",
      "bot":{
         "url":"https://t.me/best_bot",
         "external_id":1845126570800,
         "id":"60b0a854b4d8056773f592b92f3",
         "name":"BEST"
      },
      "contact":{
         "username":"veronica",
         "name":"veronica",
         "tags":[
            
         ],
         "last_message":"Test",
         "photo":null,
         "variables":{
            "name":"Veronica Petrova",
            "Phone":"380985236985",         
            "Email":"test@gmail.com"
         },
        "operator":{
            "username":"test dza",
            "created_at":1723636543,
            "user_id":8356384,
            "avatar":null,
            "email":"custombot1@e.cn.ua"
         },
         "id":"60b0a854083b4964fd5670f7b65"
      },
      "date":1637756579166
   }
]

Webhook example for the Incoming messages event:

[
   {
      "info":{ // information from messenger
         "message":{
            "channel_data":{
               "message":{
                  "audio":null,
                  "from":1332678955,
                  "context":null,
                  "interactive":null,
                  "contacts":null,
                  "text":{
                     "body":"hey! whats up?"
                  },
                  "button":null,
                  "system":null,
                  "voice":null,
                  "video":null,
                  "identity":null,
                  "image":null,
                  "timestamp":1625834714,
                  "document":null,
                  "type":"text",
                  "id":"ABCDOAk1346346go-sKd--dduwQ9p",
                  "sticker":null,
                  "location":null
               },
               "message_id":"ABCDOAk1Z43535-sKd--dduwQ9p"
            },
            "id":"60e8434b446846838d8463"
         }
      },
      "service":"whatsapp",
      "title":"incoming_message",
      "bot":{
         "url":"https://wa.me/380932674329",
         "external_id":"380932674329",
         "id":"60c1c50c156845831909cf74",
         "name":"Revision_me"
      },
      "contact":{
         "username":"Alexander",
         "name":"Alexander",
         "tags":[
            
         ],
         "last_message":"hey! whats up?", // last message of the user
         "photo":null,
         "variables":{
            "dept":"Designer"
         },
         "id":"60c0f31f457479d02b7512"
      },
      "date":1625834714
   }
]

Webhook example for the Outbound messages event:

[
   {
      "info":{
         "message":{
            "channel_data":{
               "message":{
                  "disable_web_page_preview":null,
                  "text":"Click",
                  "disable_notification":null,
                  "reply_to_message_id":null,
                  "parse_mode":"HTML",
                  "reply_markup":{
                     "inline_keyboard":[
                        [
                           {
                              "payload_id":"84d30d5624-92245695-4e834560-86f4-bbdb694710b0456",
                              "callback_data":"eyJwIjoiODRkMzBkMjQtOTI5NS00ZTgwLTg2ZjQtYmJkYjY5NDcxMGIwIn05257",
                              "text":"Click",
                              "data":{
                                 "to_block_id":"3bd58f77-ef28-4f0d-9ae7-33ef71bedeb85724",
                                 "to_block":1,
                                 "button_id":"6cb63b34-a030-4e53-ba91-8f13320ad36b3687568"
                              },
                              "type":"postback",
                              "statistic_id":"6cb63b34-a030-4e53-ba91-8f13320ad36b5367637",
                              "external_id":"ce60c182-c058-4450-a002-2e500936ab536739",
                              "id":"6cb63b34-a030-4e53-ba91-8f13320ad36467346b"
                           }
                        ],
                        [
                           {
                              "payload_id":"97867499-063c-498d-9386-e26284addf1367568658",
                              "callback_data":"dummy",
                              "text":"Click",
                              "data":{
                                 "to_block_id":"9ba1c058-7ae8-429d-9d83-f674bf6635685b2f8",
                                 "to_block":null,
                                 "button_id":"bc769bd8-edef-42a6-9448-e47875b4663568999"
                              },
                              "type":"postback",
                              "statistic_id":"bc769bd8-edef-42a6-9448-e47875b46935683599",
                              "external_id":"5148a80f-0dc7-4bb9-aa26-8331a013568dfabc",
                              "id":"bc769bd8-edef-42a6-9448-e47875b46568586999"
                           }
                        ]
                     ]
                  }
               },
               "message_id":943544,
               "chat_id":6069664546956
            },
            "id":"619e3686cac8ab43e20a4a0546549"
         }
      },
      "service":"telegram",
      "title":"outgoing_message",
      "bot":{
         "url":"https://t.me/best_bot",
         "external_id":"18451208006576",
         "id":"60b0a854b4d8073f592b925675f3",
         "name":"BEST"
      },
      "contact":{
         "username":"veronica",
         "name":"veronica",
         "tags":[
            
         ],
         "last_message":"Test",
         "photo":null,
         "variables":{
            "name":"Veronica Petrova",
            "Phone":"380985236985",         
            "Email":"test@gmail.com"
         },
         "id":"60b0a854083b4964fd0f7b65675675"
      },
      "date":16377585936738
   }
]

Webhooks triggered upon reaching a flow element

These webhooks are sent whenever a user reaches a certain flow element.

Connecting webhooks

Go to the flow builder, and add Action: Send a Webhook to your flow scenario branch after which you need to send a webhook. Enter the URL to which you want to send data, and enter your webhook name.

Learn more: How to enable a webhook in a flow.

Webhook example*:

[
   {
        "info": null, 
        "service": "messenger", 
        "title": "Reserved. Apartment #3" 
        "bot": {
            "url": "https://m.me/104117781360763",
            "external_id": "104117781360763", 
            "id": "17ff4105-d5f1-4790-9d09-a6f64ea73d54", 
            "name": "BEST" // 
        },
        "contact": {
           "name of variable": "value of variable",
            "email": "name@example.com",
            "phone": "+38093000000",
            "last_message": "hey! whats up?", 
            "photo": "https://..",
            "tags": ["tag1", "tag2"],
            "id": "467bf50f-9cb0-4b65-b722-0135ad5fb9e0", 
            "name": "Alexander"
        },
        "date": 1617401679 
    }
]

*The webhook structure is the same as in global webhooks. You can find out more in the Webhook structure section of this article.

Payment webhooks

These webhooks are sent whenever the statuses of payments received from users in the Chatbots, Websites, CRM, EDU, and Email sections are updated.

Connecting webhooks

Go to Account settings > API. In Webhooks > Success payments webhooks, click Create webhook. Enter the URL to which you want to send data, and enter your webhook name.

Learn more: How to send a successful payment webhook and How to view payment statuses.

Webhook structure

Webhooks can pass the following data:

Parameter Type Description
timestamp int Webhook trigger date and time in milliseconds.
version string Webhook version. By default, it’s 1.0.
event string Webhook event name. By default, it’s payment_order.
order array Order data
totalCost int Order cost
status int Payment status. It can have the following statuses:

100 — Payment in processing;

101 — Pending payment (the user followed the link to the payment system page but has not paid yet);

102 — Pending payment processing (the user has paid, but their bank has not transferred the funds to the payment system yet);

103 — Payment to be reviewed;

104 — Payment on hold;

200 — Payment completed successfully;

300 — Payment canceled;

301 — Payment returned by the seller;

302 — Payment returned by the payment system;

303 — Payment denied;

304 — The user clicked through but did not pay;

305 — Payment partially returned by the seller;

400 — Payment was not received in full;

500 — Payment error.
customerName string Order payer name
service int SendPulse section that processed the payment:

1 — Facebook Messenger chatbot;

3 — Telegram chatbot;

4 — WhatsApp chatbot;

5 — Instagram chatbot;

100 — Websites;

200 — EDU;

300 — Email;

400 — CRM.
paymentMethodType int Payment system that processed the payment:

2 — PayPal;

3 — Fondy;

6 — Stripe;

7 — MercadoPago;

8 — LiqPay;

9 — WayForPay;

10 — FlutterWave;

11 — Monobank;

12 — Cryptomus.
variables array Contact variables
valueType int Variable type. Possible values:

1 – String (maximum length is 500 characters);

2 – Number (possible range is +-1000000000000);

3 – Date (the 'Y-m-d' format);

4 – Boolean;

5 – Phone;

6 – Email;

7 – URL;

9 – Date time (the 'Y-m-d H:i' format);

10 – Time (the 'H:i' string format).
name string Variable name
value string Variable value
number int Payment serial number
currency string Payment currency retrieved from the account settings.
contactId string SendPulse contact ID.
updatedAt string Payment status update date.
type int Payment type. Possible values:

1 — actual payment;

2 — test payment;

3 — live test payment.
id $uuid4 string SendPulse payment ID
createdAt string The payment creation date is when the user clicked the “Buy” button.
description string Product description retrieved from payment element settings in the builder.

Webhook example for the Payment Order event:

{
  "timestamp": 1644590834,
  "version": "1.0",
  "event": "payment_order",
  "order": {
    "totalCost": 12,
    "status": 200,
    "customerName": "User",
    "service": 2,
    "paymentMethodType": 7,
    "variables": [
      {
        "valueType": 1,
        "name": "String",
        "value": "Hello World"
      },
      {
        "valueType": 2,
        "name": "Number",
        "value": "55684213"
      },
      {
        "valueType": 3,
        "name": "Date",
        "value": "2022-02-25"
      },
      {
        "valueType": 5,
        "name": "Phone",
        "value": "+38063456228"
      },
      {
        "valueType": 6,
        "name": "Email",
        "value": "user@sendpulse.com"
      },
      {
        "valueType": 7,
        "name": "Link",
        "value": "http://sendpulse.com"
      }
    ],
    "number": 1618,
    "currency": "BRL",
    "contactId": "7a505f4293dffcd7100f8f0004214892e4cf5618307908edf465042075d5c30",
    "updatedAt": "2022-02-11T14:47:14+00:00",
    "type": 2,
    "id": "a3704313-8c0b-0000-b195-c6b84242f0e2",
    "createdAt": "2022-02-11T14:47:13+00:00",
    "description": "Apple MercadoPago"
  }
}