Webhooks

Updated at March 28th, 2025

+ More

Table of Contents

Overview Webhook Structure Xml Example Object Event Subscriptions User Events Subscriptions Satisfaction Events Subscriptions Form Events Subscriptions Chat Events Subscriptions

Overview

A webhook sends an HTTP POST request to a specified URL responding to a trigger (an “event”) in Cirrus. For example, every time a new user is created or deleted, Cirrus will send a notification to the callback URL provided by the client. The webhook system of notification and updates eliminates continuous or periodic requests when changes haven’t occurred.

Note: We strongly recommend using an HTTPS callback URL with a strong encrypted certificate.

To register for this service, contact your Cirrus CS.

Webhook Structure

All updates contain a wrapper called “Event,” which indicates the subscription source and name of the trigger event. Inside the wrapper will be the actual data relevant to this update.

Note: Notifications can be transferred as XML objects.

Xml Example

For a new object that was received on Cirrus’ servers, an “OnNew” event will be triggered and posted to the client callback URL:

<Event Subscription="Object" Name="OnNew">
  <Object Id="123456" StreamId="1" SubStreamId="1" Type="0" StatusID="1" CreateDate="2014-09-23 12:39:11">
  <Message>New status from facebook, Hello world!</Message>
  <Content>{"num_likes":5,"user_likes":false,"num_shares":2}</Content>
    <User Id="123" UniqueID="123" Phone1="972526444555" Phone2="" Email="yuval@gmail.com" FirstName="Yuval"
     LastName="Hakim" Gender="M" NumIdentities="3" Locale="en_US" Birthday="1951-10-10"
     Remarks="User remarks">
      <Identity Id="12345" StreamProviderId="11111111" StreamProviderType="1"
       StreamProviderEmail="yuval@gmail.com" UserName="yuvalh" FirstName="Yuval"
       LastName="Hakim" ThumbnailUrl="//graph.facebook.com/11111111/picture" NumObjects="13">
      </Identity>
    </User>
  </Object>
</Event>

Object Event Subscriptions

OnNew

This event is triggered by creating a new object (conversation).

<Event Subscription="Object" Name="OnNew" Brand="cirrus">
  <Object Id="123456" StreamId="1" SubStreamId="1" Type="5"
  StatusID="1" CreateDate="2014-09-23 12:39:11"
  StreamProviderId="CAEooBmqRVHRrfRmOcCSzSsYMUHUu5NY+NA@mail.gmail.com" StreamProviderType="Mail">
  <Message>New status from facebook, Hello world!</Message>
  <Content>{"num_likes":5,"user_likes":false,"num_shares":2}</Content>
  <ManagerId>0</ManagerId>
  <Snippet>Hello</Snippet>
    <User Id="123" UniqueID="123" Phone1="972501111111" Phone2=""
    Email="yuval@gmail.com" FirstName="Yuval" LastName="Hakim"
    Gender="M" NumIdentities="3" Locale="en_US" Birthday="1951-10
    10" Remarks="User remarks" NumObjects="13">
    <Content>{}</Content>
      <Identity Id="12345" StreamProviderId="11111111"
      StreamProviderType="1"
      StreamProviderEmail="yuval@gmail.com"
      UserName="yuvalh" FirstName="Yuval" LastName="Hakim"
      ThumbnailUrl="//graph.facebook.com/11111111/picture">
      </Identity>
    </User>
  </Object>
</Event>

OnNewChild

This event is triggered by creating a new child object (message in a conversation).

<Event Subscription="Object" Name="OnNewChild" Brand="cirrus">
  <Object Id="901730" StreamId="71" SubStreamId="0">
    <Children>
      <Child Id="2099753" CreateDate="26-03-2017 06:36:15" 
      Type="0" StreamProviderId="CAEooBmqRVHRrfRm5NY+NA@mail.gmail.com" StreamProviderType="Mail">
      <Message>Hello</Message>
      <ManagerId>0</ManagerId>
      <Content>{"sessionId":133}</Content>
      <Snippet>Hello</Snippet>
        <User Id="1798715" Phone1="97243434343" Phone2="" 
        UniqueID="" Email="" FirstName="michael" 
        LastName="kantz" NumIdentities="1" Locale=""
        Remarks="" NumObjects="1">
        <Content>{}</Content>
          <Identity Id="2191863" 
          StreamProviderId="43434343"
          StreamProviderType="5" 
          StreamProviderEmail="michael.k@gmail.com" 
          UserName="" FirstName="michael"
          LastName="kantz" 
          ThumbnailUrl="//graph.facebook.com/146582153
          /picture"/>
        </User>
      </Child>
    </Children>
  </Object>
</Event>

OnNewActivity

The following events can be triggered by the creation of a new activity:

(a) New remark activity
Example:

<Event Subscription="Object" Name="OnNewActivity" Brand="cirrus">
  <Object Id="901738" StreamId="71" SubStreamId="0">
    <Activities>
      <Activity Id="565533" Type="1" CreateDate="27-03-2017 06:29:59">
        <User Id="433178">
        <Identity Id="16982" />
        </User>
        <Data>{"text":"New remark"}</Data>
      </Activity>
    </Activities>
  </Object>
</Event>

(b) Status change activity
Example:

<Event Subscription="Object" Name="OnNewActivity" Brand="cirrus">
  <Object Id="901731" StreamId="71" SubStreamId="0">
    <Activities>
      <Activity Id="565420" Type="2" 
      CreateDate="26-03-2017 06:57:33">
      <User Id="433178">
      <Identity Id="16982" />
      </User>
      <Data>{"statusId": 8}</Data>
      </Activity>
    </Activities>
  </Object>
</Event>

<Event Subscription="Object" Name="OnNewActivity" Brand="cirrus">
  <Object Id="901738" StreamId="71" SubStreamId="0">
  <Activities>
    <Activity Id="565534" Type="3" CreateDate="27-03-2017 06:29:59">
      <User Id="433178">
      <Identity Id="16982" />
      </User>
      <Data>{"message":"forward object","recipients":["john.k@gmail.com"],
      "allowEmailReply":true,"allowCustomerDetails":true}
      </Data>
      </Activity>
    </Activities>
    </Object>
</Event>

(d) Reply to forwarded object activity
Example:

<Event Subscription="Object" Name="OnNewActivity" Brand="cirrus">
  <Object Id="901738" StreamId="71" SubStreamId="0">
    <Activities>
      <Activity Id="565532" Type="4" CreateDate="27-03-2017 
      06:29:59">
      <User Id="123" />
      <Data>{"message":"test
      test","recipients":["john.k@gmail.com"],
      "attachments":"{}"}</Data>
      </Activity>
    </Activities>
  </Object>
</Event>

(e) Object stream change
Example:

<Event Subscription="Object" Name="OnNewActivity" Brand="cirrus">
  <Object Id="901738" StreamId="71" SubStreamId="0">
    <Activities>
      <Activity Id="565533" Type="5" CreateDate="27-03-2017 
      06:29:59">
      <User Id="123" />
      <Data>{"oldObjectSubstreamName":"old_stream_name","oldObjectStreamName":"old_sub_stream_name",
      "newObjectStreamName":"new_stream_name", "newObjectSubstreamName":"new_sub_stream_name"}</Data>
      </Activity>
    </Activities>
  </Object>
</Event>

(f) New manager assignment
Example:

<Event Subscription="Object" Name="OnNewActivity" Brand="cirrus">
  <Object Id="901733" StreamId="71" SubStreamId="0">
    <Activities>
      <Activity Id="565443" Type="6" CreateDate="26-03-2017 
      08:45:50">
      <User Id="4342094">
      <Identity Id="16982" />
      </User>
      <Data>{"managerId":4342094,"assignedManagerId":4342094}</Data>
      </Activity>
    </Activities>
  </Object>
</Event>

(g) Update object tag
Example:

<Event Subscription="Object" Name="OnNewActivity" Brand="cirrus">
  <Object Id="901733" StreamId="71" SubStreamId="0">
    <Activities>
      <Activity Id="565443" Type="7" CreateDate="26-03-2017 
      08:45:50">
      <User Id="4342094">
      <Identity Id="16982" />
      </User>
      <Data>{"tagId":11,"objectId":4342094,"isRemoveTag":false,"name":"tag1","group_name":"group1"}</Data>
      </Activity>
    </Activities>
  </Object>
</Event>

(h) Follow up object activity
Example:

<Event Subscription="Object" Name="OnNewActivity" Brand="cirrus">
  <Object Id="901733" StreamId="71" SubStreamId="0">
    <Activities>
      <Activity Id="565443" Type="8" CreateDate="26-03-2017 
      08:45:50">
      <User Id="433178">
      <Identity Id="16982" />
      </User>
      <Data>{"text": "test follow up" ,
      "scheduledTime": "03/28/2017 05:30:00"}</Data>
      </Activity>
    </Activities>
  </Object>
</Event>

(i) Update object intent
Example:

<Event Subscription="Object" Name="OnNewActivity" Brand="cirrus">
  <Object Id="901733" StreamId="71" SubStreamId="0">
    <Activities>
      <Activity Id="565443" Type="9" CreateDate="26-03-2017 
      08:45:50">
      <User Id="4342094">
      <Identity Id="16982" />
      </User>
      <Data>{"intentIds":[11],"objectId":4342094,"isRemoveIntent":false,"names":["tag1"]}</Data>
      </Activity>
    </Activities>
  </Object>
</Event>

(j) Update object attachments
Example:

<Event Subscription="Object" Name="OnNewActivity" Brand="cirrus">
  <Object Id="901733" StreamId="71" SubStreamId="0">
    <Activities>
      <Activity Id="565443" Type="10" CreateDate="26-03-2017 
      08:45:50">
      <User Id="4342094">
      <Identity Id="16982" />
      </User>
      <Data>{"objectId":4342094,"managerId":452224,
      "attachments":{"attachments":[{"href":"/media/Brands/test//5-17/test_image.png","name":"test_image"}]},
      "attachmentType":"videoCapture"}</Data>
      </Activity>
    </Activities>
  </Object>
</Event>

(k) Object routed
Example:

<Event Subscription="Object" Name="OnNewActivity" Brand="cirrus">
  <Object Id="901733" StreamId="71" SubStreamId="0">
    <Activities>
      <Activity Id="565443" Type="11" CreateDate="26-03-2017 
      08:45:50">
      <User Id="4342094">
      <Identity Id="16982" />
      </User>
      <Data>{"originalStreamId":12222,"destStreamId":114444,"destSubStreamId":11,"changedStatusId":4,
      "tagId":353,"tagName":"plus_tag"}}</Data>
      </Activity>
    </Activities>
  </Object>
</Event>

(l) Update object publicity
Example:

<Event Subscription="Object" Name="OnNewActivity" Brand="cirrus">
  <Object Id="901733" StreamId="71" SubStreamId="0">
    <Activities>
      <Activity Id="565443" Type="13" CreateDate="26-03-2017 
      08:45:50">
      <User Id="4342094">
      <Identity Id="16982" />
      </User>
      <Data>{"changePublicityToPublic":false}</Data>
      </Activity>
    </Activities>
  </Object>
</Event>

(m) Unvalid extension file
Example:

<Event Subscription="Object" Name="OnNewActivity" Brand="cirrus">
  <Object Id="901733" StreamId="71" SubStreamId="0">
    <Activities>
      <Activity Id="565443" Type="15" CreateDate="26-03-2017 
      08:45:50">
      <User Id="4342094">
      <Identity Id="16982" />
      </User>
      <Data>{"fileName":"3c3b71_IMG_1988.jpeg","status":"failed",
      "description":"Unsupported file type: image/heic extension: jpeg","unValidActivity":15,
      "fileExtension":"jpeg"}</Data>
      </Activity>
    </Activities>
  </Object>
</Event>

(n) Unvalid file size
Example:

<Event Subscription="Object" Name="OnNewActivity" Brand="cirrus">
  <Object Id="901733" StreamId="71" SubStreamId="0">
    <Activities>
      <Activity Id="565443" Type="16" CreateDate="26-03-2017 
      08:45:50">
      <User Id="4342094">
      <Identity Id="16982" />
      </User>
      <Data>{"status":"failed","description":"File is too big","maxFileSizeAllow": 10,
      "unValidActivity":16}</Data>
      </Activity>
    </Activities>
  </Object>
</Event>

(o) Unallowed file upload
Example:

<Event Subscription="Object" Name="OnNewActivity" Brand="cirrus">
  <Object Id="901733" StreamId="71" SubStreamId="0">
    <Activities>
      <Activity Id="565443" Type="17" CreateDate="26-03-2017 
      08:45:50">
      <User Id="4342094">
      <Identity Id="16982" />
      </User>
      <Data>{"status":"failed","description":"media dos not enabled","unValidActivity":17}</Data>
      </Activity>
    </Activities>
  </Object>
</Event>

(p) Inactivity logout
Example:

<Event Subscription="Object" Name="OnNewActivity" Brand="cirrus">
  <Object Id="901733" StreamId="71" SubStreamId="0">
    <Activities>
      <Activity Id="565443" Type="18" CreateDate="26-03-2017 
      08:45:50">
      <User Id="4342094">
      <Identity Id="16982" />
      </User>
      <Data>{}</Data>
      </Activity>
    </Activities>
  </Object>
</Event>

(q) Participants change
Example:

<Event Subscription="Object" Name="OnNewActivity" Brand="cirrus">
  <Object Id="901733" StreamId="71" SubStreamId="0">
    <Activities>
      <Activity Id="565443" Type="19" CreateDate="26-03-2017 
      08:45:50">
      <User Id="4342094">
      <Identity Id="16982" />
      </User>
      <Data>{"action":"addParticipant","performingAgentId":192229,"isAgent":true,
      "addedParticipantName":"tomer_b"}</Data>
      </Activity>
    </Activities>
  </Object>
</Event>

OnUpdateTag

These events are triggered by an update of a tag relating to the object (conversation tag):

(a) Add
Example:

<Event Subscription="Object" Name="OnUpdateTag" Brand="cirrus">
  <Object Id="901731" StreamId="71" SubStreamId="0">
    <Tags>
    <Tag Id="1608" Action="Add" />
    </Tags>
  </Object>
</Event>

(b) Remove
Example:

<Event Subscription="Object" Name="OnUpdateTag" Brand="cirrus">
  <Object Id="901731" StreamId="71" SubStreamId="0">
    <Tags>
    <Tag Id="1611" Action="Remove" />
    </Tags>
  </Object>
</Event>

User Events Subscriptions

Events in this section indicate a change that occurred in Cirrus monitored user(s). The change may be the creation of a new user or an update of an existing one. All updates must contain the surrounding “Event” property and a “User” property and may contain additional properties.

OnNew

This event is triggered by the creation of a new user.

Example:

<Event Subscription="User" Name="OnNew" Brand="cirrus">
  <User Id="1798714" Phone1="97252570000" Phone2="" UniqueID="" Email="john.doe@gmail.com"
   FirstName="michaeli" LastName="" NumIdentities="1" Locale="en_US" Remarks="" NumObjects="0">
  <Content>{}</Content>
  <Identity Id="2191862" StreamProviderId="kantzmichaeli@gmail.com" StreamProviderType="4"
   StreamProviderEmail="" UserName="michaelk" FirstName="michaeli" LastName="kantz" ThumbnailUrl="" />
  </User>
</Event>

OnUpdate

This event is triggered by an update of a user.

Example:

<Event Subscription="User" Name="OnUpdate" Brand="cirrus">
  <User Id="1710055" Phone1="97252570000" Phone2="972525757054" UniqueID="206064"
   Email="kantzmichael@gmail.com" FirstName="michael" LastName="kantz" Gender="M" NumIdentities="1"
   Locale="" Remarks="New user details">
  <Content>{}</Content>
  </User />
</Event>

OnUpdateTag

This event is triggered by an update of a tag relating to the user.

Example:

<Event Subscription="User" Name="OnUpdateTag" Brand="cirrus">
  <User Id="1798718" Phone1="972525757054" Phone2="972525757054" 
  UniqueID="" Email="michael.k@gmail.com" FirstName="michael" 
  LastName="" NumIdentities="1" Locale="" Remarks="" 
  Content="{}">
    <Tags>
    <Tag Id="1073" Action="Add" />
    </Tags>
  </User>
</Event>

Satisfaction Events Subscriptions

This section contains events that describe customer satisfaction reports. Updates must contain a surrounding “Event” property and a “Satisfaction” property.

OnSubmit

This event is triggered by a submission of a satisfaction report relating to some object (conversation).

Example:

<Event Subscription="Satisfaction" Name="OnSubmit" Brand="cirrus">
  <Satisfaction ObjectId="901733">
  <Score>100</Score>
  <Description>excellent</Description>
  </Satisfaction>
</Event>

Form Events Subscriptions

This section contains events that occurred when a form is created or changed. Updates must contain a surrounding “Event” property and a “Form” property.

OnSubmit

This event is triggered when a customer submits a form, and the form PDF file is saved on the disk.

Example:

<Event Subscription="Form" Name="OnSubmit" Brand="cirrus">
  <Form
  <ObjectId>901733</ObjectId>
  <FormUrl> https://apps.commboxdev.io/form...</FormUrl>
  <Properties>{“field_0”:”Jhon”,”my_own_param”:”1234”}</Properties>
  </Form>
</Event>

Chat Events Subscriptions

This section contains events that occurred when the user closes the chat window or disconnects.

OnUserExit

This event is triggered when the user closes the chat window or disconnect.

Example:

<Event Subscription="Chat" Name="OnUserExit" Brand="cirrus">
  <Chat>
    <User id="901733"></User>
    <Object id="901735"></Object>
  </Chat>
</Event>

Contact Us

Webhooks

Contact Us

Overview

Webhook Structure

Xml Example

Object Event Subscriptions

OnNew

OnNewChild

OnNewActivity

OnUpdateTag

User Events Subscriptions

OnNew

OnUpdate

OnUpdateTag

Satisfaction Events Subscriptions

OnSubmit

Form Events Subscriptions

OnSubmit

Chat Events Subscriptions

OnUserExit

Related Articles