Overview of Webhook


For users who would like to build your own custom workflow where Saleswhale updates your existing systems, you can do so with our webhook.

In this guide, we will cover:

  • Setup of webhook
  • Events that trigger our webhook
  • Conversation.ended event

There are also API endpoints available. You can refer to our webhook documentation here.


Setup of webhook

You need to first add in your Target URL in the app under Account Settings.


For more details on how to setup your webhook, please refer to our documentation here.


Events that trigger our webhook 

Currently, our webhook will fire on the following events:

  • Conversation.ended


Conversation.ended event 


Conversation.ended event will be triggered whenever a conversation status changes to a 'terminal' status.

A conversation can either be ongoing or completed. This is determined by the status on the conversation:

  • Ongoing conversation statuses (non-terminal statuses) : Pending lead response, Pending bot response
  • Completed conversation statuses (terminal statuses) : Bounced, Human Review, Not Interested, Qualified, Stopped Responding, Unresponsive, Cancelled

When a conversation is completed, it will have a 'terminal' conversation status and this will trigger the webhook. These statuses are representative of the final state of the conversation, with a couple of exceptions:

  • If the Human Review Owner marks a human review task as 'Completed', the status can change from 'Human Review' to 'Qualified', 'Stopped Responding', 'Cancelled' or 'Not Interested', which will trigger the webhook again.
  • If a lead subsequently responds after the final email has already gone out, the status can change from 'Unresponsive' or 'Stopped Responding' to other statuses. When the conversation is finally completed and the status updates to a 'terminal' status, it will trigger the webhook again.


Interpreting the response

The response returns the following properties in the `event_payload` object:

Property  Type Description
conversation  object

You can retrieve details on the conversation that triggered the webhook.

With the conversation.id, you can retrieve the conversation details.

With the conversation.handover_rep.id, you can do a matching to retrieve the sales rep it was handed over to.

leads  array

For most conversations, there will only be one lead returned.

In a conversation where your lead refers the bot to their colleague, or CCs in other people, there will be multiple leads in a conversation.

All leads within a conversation will have the same conversation status.

With the lead.id, you will be able to retrieve the details of each lead.

`is_main` refers to the main lead when the conversation is completed, which is assumed to be the last person who replied the bot. If marked as true, this lead is the 'To' recipient. If false, this lead is either a 'CC' or 'BCC' recipient.

`is_original` refers to the lead we first started the conversation on.

status  string

This is the status of the conversation when the webhook was triggered.

You can read more on conversation statuses here.

enrolment  object

You can retrieve details on the enrolment that triggered the conversation.

With the enrolment.campaign_id, you can do a matching and retrieve the campaign the lead was enrolled to.

With the enrolment.lead_id, you can retrieve the original lead whom the conversation was started on.


If you have any feedback on our webhook and how to improve it, we would love to hear from you. You can submit your product feedback at feedback [at] saleswhale.com.



0 out of 0 found this helpful



Article is closed for comments.