Skip to content
A demonstration of how to receive and process webhooks from
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.

sipgate logo Python incoming call example

This example demonstrates how to receive and process webhooks from

For further information regarding the push functionalities of please visit


  • python3
  • pip3

Enabling for your sipgate account

In order to use, you need to book the corresponding package in your sipgate account. The most basic package is the free S package.

If you use sipgate basic or simquadrat you can book packages in your product's feature store. If you are a sipgate team user logged in with an admin account you can find the option under Account Administration > Plans & Packages.

How webhooks work

What is a webhook?

A webhook is a POST request that makes to a predefined URL when a certain event occurs. These requests contain information about the event that occurred in application/x-www-form-urlencoded format.

This is an example payload converted from application/x-www-form-urlencoded to JSON:

  "event": "newCall",
  "direction": "in",
  "from": "492111234567",
  "to": "4915791234567",
  "user": [ "Alice" ],
  "xcid": "123abc456def789",
  "diversion": "1a2b3d4e5f"
} webhook events offers webhooks for the following events:

  • newCall: is triggered when a new incoming or outgoing call occurs
  • onAnswer: is triggered when a call is answered – either by a person or an automatic voicemail
  • onHangup: is triggered when a call is hung up
  • dtmf: is triggered when a user makes an entry of digits during a call

Note: Per default only sends webhooks for newCall events. To subscribe to other event types you can reply to the newCall event with an XML response. This response includes the event types you would like to receive webhooks for as well as the respective URL they should be directed to. You can find more information about the XML response here:

Configure webhooks for

You can configure webhooks for as follows:

  1. Navigate to and login with your sipgate account credentials.
  2. Select the Webhooks > URLs tab in the left side menu
  3. Click the gear icon of the Incoming or Outgoing entry
  4. Fill in your webhook URL and click save. Note: your webhook URL has to be accessible from the internet. (See the section Making your computer accessible from the internet)
  5. In the sources section you can select what phonelines and groups should trigger webhooks.

Making your computer accessible from the internet

There are many possibilities to obtain an externally accessible address for your computer. In this example, we use the service which sets up a reverse ssh tunnel that forwards traffic from a public URL to your localhost. The following command creates the specified subdomain at and sets up a tunnel between the public port 80 on their server and your localhost:8080:

$ ssh -R [subdomain]

If you run this example on a server which can already be reached from the internet, you do not need the forwarding. In that case, the webhook URL needs to be adjusted accordingly.

Get the code example:

Clone Repository with HTTPS

git clone

Clone Repository with SSH

git clone

Navigate to the project's root directory.

Install dependencies:

Please run the following command:

$ pip3 install -r requirements.txt


Run the application:

python -m incoming_call 

How It Works

In the, which is a starting point of the application, we import the server module from our file on the same directory. It contains a Flask application called app, which is started by calling its run() method with the desired port 8080.

import incoming_call.server as server

if __name__ == "__main__":

The application's behavior is defined in the script.

At first, we import the necessary libraries, Flask for starting the server and json for transforming the request data:

import flask
import json

We then create an HTTP server using the Flask framework:

app = flask.Flask(__name__)

Afterwards, we specify a route that handles incoming POST requests with the function receive_new_call(). It returns an empty string and the corresponding HTTP status code 204 indicating that there is no content:

@app.route('/', methods=["POST"])
def receive_new_call():
    return '', 204

Within the receive_new_call() function, we extract the application/x-www-form-urlencoded data from the request as a dictionary. In the next step, we format this dictionary into more readable JSON data. We then print that data to the console.

    request_data = flask.request.form.to_dict()
    json_data = json.dumps(request_data, indent=2)

Common Issues

web app displays "Feature not booked."

Possible reasons are:

  • the feature is not booked for your account

See the section Enabling for your sipgate account for instruction on how to book

"OSError: [Errno 98] Address already in use"

Possible reasons are:

  • another instance of the application is already running
  • the specified port is in use by another application

"PermissionError: [Errno 13] Permission denied"

Possible reasons are:

  • you do not have permission to bind to the specified port. This usually occurs if you try to use port 80, 443 or another well-known port which can only be bound with superuser privileges

Call happened but no webhook was received

Possible reasons are:

  • the configured webhook URL is incorrect
  • the SSH tunnel connection broke
  • webhooks are not enabled for the phoneline that received the call


Contact Us

Please let us know how we can improve this example. If you have a specific feature request or found a bug, please use Issues or fork this repository and send a pull request with your improvements.


This project is licensed under The Unlicense (see LICENSE file).

External Libraries

This code uses the following external libraries | @sipgateio | API-doc

You can’t perform that action at this time.