Setting up the Webhooks integration

Webhooks are a simple yet extremely flexible way to send data to external sources from CircleLoop. Webhooks make use of normal HTTP requests containing a JSON payload.

Go to Settings > Notifications in your CircleLoop app, populate the Webhook URL with your endpoint URL and select the HTTP method for which you'd like to receive the request.  Requests can be sent with your choice of a GET | PUT | POST | DELETE.

Then select one or more event types and click "Save".

The following groups of events can fire webhook requests.  Each of the event types supported contains a JSON payload specific to it's type.

  • Call Events
  • Message Events(Voicemail)

Call Events

The structure of JSON payload for call events are identical with the exception of the "eventType" property value.

Example Call Ringing JSON

Example Call Missed JSON

object string
This is always set to a value of event

eventType string
This denotes the type of event that fired the request:   call_ringing | call_missed

userID GUID
Unique reference which identifies the user

callID GUID
Unique reference which identifies the call

originatingNumberE164 string
The phone number of the caller in E164 format (international numbering format)

originatingNumber string
The phone number of the caller in local format

dialledNumberE164 string
The dialled phone number in E164 format (international numbering format)

dialledNumber string
The dialled phone number in local format

created timestamp
Date / time of the event in Unix timestamp format 

Message Event Types

Example Message Received JSON

object string
This is always set to a value of event

eventType string
This denotes the type of event that fired the request:   message_received

userID GUID
Unique reference which identifies the user

messageID GUID
Unique reference which identifies the voice message

messageAttachmentURL string
The URL of the voice message file (mp3 format)

originatingNumberE164 string
The phone number of the caller in E164 format (international numbering format)

originatingNumber string
The phone number of the caller in local format

dialledNumberE164 string
The dialled phone number in E164 format (international numbering format)

dialledNumber string
The dialled phone number in local format

created timestamp
Date / time of the event in Unix timestamp format 

Testing your Webhooks

To test your webhooks we recommend using  RequestBin.

RequestBin gives you a URL that will collect requests made to it and let you inspect them in a human-friendly way.  You can use RequestBin to see what your HTTP client is sending or to inspect and debug webhook requests.

Just head to  RequestBin and get your URL then enter it into the Webhooks app in your CircleLoop account.  When events fire then you should see something similar to this in RequestBin.

RequestBin Example

Need to use multiple endpoints?

Unfortunately we don't currently support being able to send requests for different events to multiple URLs or to use different HTTP methods.  If you'd like to see this feature added at some point then get in touch with and we'll see what we can do for you.