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
  • Payment 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

{
    "object": "event",
    "eventType": "call_ringing",
    "userID": "00000000-0000-0000-0000-6bbe00000000",
    "callID": "00000000-0000-0000-0000-35fb00000000",
    "originatingNumberE164": "447888123456",
    "originatingNumber": "07888 123456",
    "dialledNumberE164": "443301234567",
    "dialledNumber": "0330 123 4567",
    "created": 1465829384
}

Example Call Missed JSON

{
    "object": "event",
    "eventType": "call_missed",
    "userID": "00000000-0000-0000-0000-6bbe00000000",
    "callID": "00000000-0000-0000-0000-35fb00000000",
    "originatingNumberE164": "447888123456",
    "originatingNumber": "07888 123456",
    "dialledNumberE164": "443301234567",
    "dialledNumber": "0330 123 4567",
    "created": 1465829384
}

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": "event",
    "eventType": "message_received",
    "userID": "00000000-0000-0000-0000-6bbe07918780",
    "messageID": "00000000-0000-0000-0000-3869336f8a5b",
    "messageAttachmentURL": "https://circleloop-voicemail.s3-eu-west-1.amazonaws.com/00000000-0000-0000-0000-a1904c7d2b65/00000000-0000-0000-0000-6bbe07918780/00000000-0000-0000-0000-3869336f8a5b.mp3",
    "originatingNumberE164": "447888123456",
    "originatingNumber": "07888 123456",
    "dialledNumberE164": "443301234567",
    "dialledNumber": "0330 123 4567",
    "created": 1465897362
}

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 

Payment Event Types

Example Invoice Paid JSON

{
    "object": "event",
    "eventType": "invoice_paid",
    "clientID": "00000000-0000-0000-0000-5a7d303a8737",
    "invoiceID": "00000000-0000-0000-0000-cf2e339f5ca3",
    "invoiceClientReference": "1111-1111111",
    "invoiceTotal": 1200,
    "invoiceTotalGBP": "12.00",
    "invoiceSubtotal": 1000,
    "invoiceSubtotalGBP": "10.00",
    "invoiceCurrency": "gbp",
    "adminUserID": "00000000-0000-0000-0000-0243c36a952f",
    "paymentID": "00000000-0000-0000-0000-2dab330d6238",
    "paymentAmount": 1200,
    "paymentAmountGBP": "12.00",
    "paymentCurrency": "gbp",
    "first": true
}

Example Invoice Failed JSON

{
    "object": "event",
    "eventType": "invoice_failed",
    "clientID": "00000000-0000-0000-0000-5a7d303a8737",
    "invoiceID": "00000000-0000-0000-0000-cf2e339f5ca3",
    "invoiceClientReference": "1111-1111111",
    "invoiceTotal": 1200,
    "invoiceTotalGBP": "12.00",
    "invoiceSubtotal": 1000,
    "invoiceSubtotalGBP": "10.00",
    "invoiceCurrency": "gbp",
    "adminUserID": "00000000-0000-0000-0000-0243c36a952f",
    "paymentID": "00000000-0000-0000-0000-2dab330d6238",
    "paymentAmount": 1200,
    "paymentAmountGBP": "12.00",
    "paymentCurrency": "gbp"
}

object string
This is always set to a value of event

eventType string
This denotes the type of event that fired the request:   invoice_paid | invoice_failed

clientID GUID
Unique reference which identifies the CircleLoop account

invoiceID GUID
Unique reference which identifies the invoice

invoiceClientReference string
Invoice number as displayed on the invoice

invoiceTotal integer
The total amount of the invoice including VAT - the amount is in pence

invoiceTotalGBP decimal
The total amount of the invoice including VAT - the amount is in pounds

invoiceSubtotal integer
The total amount of the invoice excluding VAT - the amount is in pence

invoiceSubtotalGBP decimal
The total amount of the invoice excluding VAT - the amount is in pounds

invoiceCurrency string
The currency of the invoice - this is always set to gbp to denote Great Britain Pounds or UK Sterling

adminUserID GUID
Contains the userID of the person who initiated the payment.  If the payment is due to an item which is set to auto-renew, then the property will be excluded

paymentID GUID
Unique reference which identifies the payment or payment attempt

paymentAmount integer
The amount in pence Sterling of the payment / payment attempt

paymentAmountGBP decimal
The amount in pounds of the payment / payment attempt

paymentCurrency string
The currency of the payment - this is always set to gbp to denote Great Britain Pounds or UK Sterling

first boolean Only present on invoice_failed event.  Marks whether this is the first payment against the CircleLoop account

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.

Did this answer your question?