Webhooks
Configure a campaign to trigger webhooks
Overview
SIP Caller can trigger webhooks in order to notify external systems about events that happen on our platform. In this way, many useful custom integrations can be developed between SIP Caller and other systems.
The procedure involves 2 steps:
- Create a webhook.
- Configure a campaign with an existing webhook.
Create a webhook
In order to create a webhook, login to SIP Caller and go to Settings > Webhooks. Then click the “Create” button to open the Webhook creation dialog and proceed as follows:
- Enter a friendly name for the webhook, so you can easily select it later.
- Enter the URL that you want SIP Caller to invoke when the events occur.
- Select the events you’re interested in.
- Configure the timeout, max retry attempts, event max age and max simultaneous conections, according to your needs.
Configure a campaign to trigger webhooks
Once the webhook is created, you need to configure the campaigns to use it. To do this, just select the webhook from the Behavior tab.
Enable and disable webhooks
If you find an issue while processing the webhooks triggered by SIP Caller, you can pause the generation of these events. When you do this, SIP Caller will queue these events during the time you configured when you created it, giving you time to fix your event processing algorithm, so you can then enable the webhooks again. To do this, go to Settings > Webhooks, and select the “Enable” or “Disable” buttons from the Actions column.
Regenerate the signing secret
From the Actions column in the webhook list, you can also click the button to regenerate the signing secret. This will cause SIP Caller to start signing the webhooks using the new secret. Any integration you have using the old secret will stop working, as the validation will fail, so you need to be careful when performing this action.
Validate webhook signature
Every webhook notification sent by SIP Caller will have the header “Sip-Caller-Signature” in the HTTP request, set to a value similar to the following:
t=1728776932,v1=df9da282f3ffe9a7d855cc11589d86d33852ee0bbc1abaacab854c7f52e6efae
The value assigned to “t” is a timestamp informing when the event was generated. The value assigned to “v1” is the webhook signature. You will need both values to do the verification, as follows:
- Concatenate the timestamp (as a string), a dot (.), and the JSON payload received in the HTTP request body. For example:
1728776932.{"id" : "01928322-860c-77f9-9c3b-7f8abe3b6afd".......}
- Calculate the expected webhook signature, by computing an HMAC using the SHA256 hash function. Use the webhook signing secret as the key, and the value resulting from the concatenation in the previous step as the message.
- Compare the calculated webhook signature with the value taken from “v1” in the request header. If both values match, then you can safely proceed with the processing of the webhook event.
Webhook troubleshooting
From the SIP Caller console > Settings > Webhooks, you can click on a webhook and check all the events that were notified.
The list can be filtered in order to identify the event you’re looking for. Then, when an event is clicked, a panel will be shown on the right side, with the details of each notification attempt.
Webhooks data reference
The webhooks generated by SIP Caller are HTTP POST requests, containing JSON as payload. The detail of the JSON data send for each event is described below:
Campaign Activated
{
"id":"01928321-9129-7f25-8ad3-80c57b16d3ed",
"object":"event",
"apiVersion":1,
"createdAt":"2024-10-12T23:47:48.133",
"type":"CampaignActivated",
"data":{
"customer":{
"id":"0192830c-58a0-7be2-8e3d-dc8997d0a631",
"name":"SIP Caller (Demo account)"
},
"campaign":{
"id":"0192831a-fbbe-735f-b385-a3252781817d",
"name":"Campaign 1",
"phoneSystem":{
"id":"01928310-2d96-7a70-bdfc-4bcd24c22c95",
"name":"My Phone System",
"extension":{
"id":"07bcd1de-1e5d-47b5-99bf-b846c7a12f09",
"name":"SIP Caller Extension"
}
},
"dialer":{
"mode":"Power"
},
"status":"Active",
"type":"Static",
"startDate":"2024-10-12",
"endDate":"2024-10-13",
"timeZoneId":"America/Argentina/Buenos_Aires",
"callflow":{
"forHuman":{
"id":"01928316-cfd7-75c7-bb6d-9128e205c53f",
"name":"Survey"
},
"forMachine":null
},
"varNames":[
"Customer Name",
"Due Balance"
],
"startedAt":null,
"endedAt":null
},
"origin":{
"user":{
"id":"0192830c-589d-7384-b157-f922afab9e55",
"name":"John Doe",
"email":"john.doe@example.com"
},
"ipAddress":"98.97.134.180"
}
}
}
Campaign Paused
{
"id":"01928323-1fcd-721d-ad19-8ce4cfc1c135",
"object":"event",
"apiVersion":1,
"createdAt":"2024-10-12T23:49:30.185",
"type":"CampaignPaused",
"data":{
"customer":{
"id":"0192830c-58a0-7be2-8e3d-dc8997d0a631",
"name":"SIP Caller (Demo account)"
},
"campaign":{
"id":"0192831a-fbbe-735f-b385-a3252781817d",
"name":"Campaign 1",
"phoneSystem":{
"id":"01928310-2d96-7a70-bdfc-4bcd24c22c95",
"name":"My Phone System",
"extension":{
"id":"07bcd1de-1e5d-47b5-99bf-b846c7a12f09",
"name":"SIP Caller Extension"
}
},
"dialer":{
"mode":"Power"
},
"status":"Paused",
"type":"Static",
"startDate":"2024-10-12",
"endDate":"2024-10-13",
"timeZoneId":"America/Argentina/Buenos_Aires",
"callflow":{
"forHuman":{
"id":"01928316-cfd7-75c7-bb6d-9128e205c53f",
"name":"Survey"
},
"forMachine":null
},
"varNames":[
"Customer Name",
"Due Balance"
],
"startedAt":"2024-10-12T23:48:05.603",
"endedAt":null
},
"origin":{
"user":{
"id":"0192830c-589d-7384-b157-f922afab9e55",
"name":"John Doe",
"email":"john.doe@example.com"
},
"ipAddress":"98.97.134.180"
}
}
}
Campaign Resumed
{
"id":"01928329-e0ae-767b-831c-eb534f0ca3ce",
"object":"event",
"apiVersion":1,
"createdAt":"2024-10-12T23:56:52.78",
"type":"CampaignResumed",
"data":{
"customer":{
"id":"0192830c-58a0-7be2-8e3d-dc8997d0a631",
"name":"SIP Caller (Demo account)"
},
"campaign":{
"id":"0192831a-fbbe-735f-b385-a3252781817d",
"name":"Campaign 1",
"phoneSystem":{
"id":"01928310-2d96-7a70-bdfc-4bcd24c22c95",
"name":"My Phone System",
"extension":{
"id":"07bcd1de-1e5d-47b5-99bf-b846c7a12f09",
"name":"SIP Caller Extension"
}
},
"dialer":{
"mode":"Power"
},
"status":"Active",
"type":"Static",
"startDate":"2024-10-12",
"endDate":"2024-10-13",
"timeZoneId":"America/Argentina/Buenos_Aires",
"callflow":{
"forHuman":{
"id":"01928316-cfd7-75c7-bb6d-9128e205c53f",
"name":"Survey"
},
"forMachine":null
},
"varNames":[
"Customer Name",
"Due Balance"
],
"startedAt":"2024-10-12T23:48:05.603",
"endedAt":null
},
"origin":{
"user":{
"id":"0192830c-589d-7384-b157-f922afab9e55",
"name":"John Doe",
"email":"john.doe@example.com"
},
"ipAddress":"98.97.134.180"
}
}
}
Campaign Canceled
{
"id":"01928761-9826-7ca4-9283-eb6f7a338c91",
"object":"event",
"apiVersion":1,
"createdAt":"2024-10-13T19:36:13.093",
"type":"CampaignCanceled",
"data":{
"customer":{
"id":"0192830c-58a0-7be2-8e3d-dc8997d0a631",
"name":"SIP Caller (Demo account)"
},
"campaign":{
"id":"01928761-27c6-7355-9add-0c4f40154847",
"name":"Campaign 1",
"phoneSystem":{
"id":"01928310-2d96-7a70-bdfc-4bcd24c22c95",
"name":"My Phone System",
"extension":{
"id":"07bcd1de-1e5d-47b5-99bf-b846c7a12f09",
"name":"SIP Caller Extension"
}
},
"dialer":{
"mode":"Power"
},
"status":"Canceled",
"type":"Static",
"startDate":"2024-10-13",
"endDate":"2024-10-13",
"timeZoneId":"America/Argentina/Buenos_Aires",
"callflow":{
"forHuman":{
"id":"01928316-cfd7-75c7-bb6d-9128e205c53f",
"name":"Survey"
},
"forMachine":null
},
"varNames":[
"Customer Name",
"Due Balance"
],
"startedAt":null,
"endedAt":"2024-10-13T19:36:13.093"
},
"origin":{
"user":{
"id":"0192830c-589d-7384-b157-f922afab9e55",
"name":"John Doe",
"email":"john.doe@example.com"
},
"ipAddress":"98.97.134.223"
}
}
}
Campaign Finished
{
"id":"01928735-88af-7fc5-ae74-81ff77bf6e61",
"object":"event",
"apiVersion":1,
"createdAt":"2024-10-13T18:48:05.526",
"type":"CampaignFinished",
"data":{
"customer":{
"id":"0192830c-58a0-7be2-8e3d-dc8997d0a631",
"name":"SIP Caller (Demo account)"
},
"campaign":{
"id":"0192831a-fbbe-735f-b385-a3252781817d",
"name":"Campaign 1",
"phoneSystem":{
"id":"01928310-2d96-7a70-bdfc-4bcd24c22c95",
"name":"My Phone System",
"extension":{
"id":"07bcd1de-1e5d-47b5-99bf-b846c7a12f09",
"name":"SIP Caller Extension"
}
},
"dialer":{
"mode":"Power"
},
"status":"Finished",
"type":"Static",
"startDate":"2024-10-12",
"endDate":"2024-10-13",
"timeZoneId":"America/Argentina/Buenos_Aires",
"callflow":{
"forHuman":{
"id":"01928316-cfd7-75c7-bb6d-9128e205c53f",
"name":"Survey"
},
"forMachine":null
},
"varNames":[
"Customer Name",
"Due Balance"
],
"startedAt":"2024-10-12T23:48:05.603",
"endedAt":"2024-10-13T18:48:05.526"
},
"origin":null
}
}
Call Ended
{
"id":"01928322-860c-77f9-9c3b-7f8abe3b6afd",
"object":"event",
"apiVersion":1,
"createdAt":"2024-10-12T23:48:50.824",
"type":"CallEnded",
"data":{
"customer":{
"id":"0192830c-58a0-7be2-8e3d-dc8997d0a631",
"name":"SIP Caller (Demo account)"
},
"campaign":{
"id":"0192831a-fbbe-735f-b385-a3252781817d",
"name":"Campaign 1",
"varNames":[
"Customer Name",
"Due Balance"
]
},
"callDetails":{
"callId":"01928322-32a3-7000-bf0d-bf1af7eda4c5",
"number":"18035551004",
"varValues":[
"Stefan Robertson",
"$99.00 "
],
"attempt":1,
"phoneSystem":{
"id":"01928310-2d96-7a70-bdfc-4bcd24c22c95",
"name":"My Phone System",
"extension":{
"id":"07bcd1de-1e5d-47b5-99bf-b846c7a12f09",
"name":"SIP Caller Extension"
}
},
"timeZoneId":"America/Argentina/Buenos_Aires",
"startedAt":"2024-10-12T23:48:29.479",
"ringResult":"Answer",
"sipResponse":{
"code":200,
"descrip":"OK"
},
"answeredAt":"2024-10-12T23:48:33.735",
"answerType":"Human",
"callflow":{
"id":"01928316-cfd7-75c7-bb6d-9128e205c53f",
"name":"Survey"
},
"endedAt":"2024-10-12T23:48:50.819",
"endType":"CallflowComplete",
"lastAction":{
"id":"535248e9-c9a2-4a15-8c1c-9d175f82ac21",
"type":"TextPrompt"
},
"duration":{
"setup":"00:00:04.256",
"established":"00:00:17.084",
"total":"00:00:21.34"
},
"gatheredData":"Question1=4|Question2=1",
"outcome":"Success",
"retryAt":null
}
}
}
