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.
Within the Webhooks app in your CircleLoop account, 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
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.
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.