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:

1. Create a webhook.
2. 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 version. We recommend using the latest version to leverage the latest features, but you can also select an older version for backward compatibility.
• 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 Integration 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:

1. 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".......}

2. 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.
3. 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.

We have created code examples showing how to do this validation in a Python or .NET application.

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, and every request is tagged with a version so we can evolve the payload format over time without breaking existing integrations. The full JSON reference for each event type and version is available on the Webhook Data Reference page.