# Handle an incoming fax with Python

Now that you know how to [send yourself a fax a using the Fax API](/docs/fax/getting-started/python/send-fax), learn how to handle incoming faxes.

In this guide you will leardn:
1. How to [set up your your Python app](#set-up-your-flask-python-application)
2. How to [start your server](#start-your-server)
3. About [webhooks](#understanding-webhooks)
4. How to [receive an incoming fax](#send-your-sinch-number-a-fax)


## What you need to know before you start

Before you can get started, you need the following already set up:

* Set all Fax API [configuration settings](/docs/fax/getting-started).
* [Python](https://www.python.org/) and a familiarity with how to create a new file.
* [PIP (package installer for Python)](https://pypi.org/project/pip/) and a familiarity with how to install Python modules.
* [Flask](https://flask.palletsprojects.com/en/2.0.x/installation/) and a familiarity with how to set up a Flask environment and app.
* [ngrok](https://ngrok.com/). You'll use ngrok to open a tunnel to your local server.


## Set up your Flask Python application

Create a new folder where you want your app project and open a command prompt to that location. Create a new environment with the following command:


```shell
py -3 -m venv venv
```

Activate the environment using the following command:


```shell
venv/Scripts/activate
```

### Install your dependencies

We will be using Flask to create a lightweight webserver that will listen for requests from the Sinch servers to handle incoming faxes. Because the webserver is running on your local machine, you will also need a method for making the server accessible over the internet. In this guide we'll be using [ngrok](https://www.ngrok.com) (and in particular the [pyngrok](https://pyngrok.readthedocs.io/en/latest/index.html) module) to do that, but if you have another way you'd prefer to do it, feel free to use that. Additionally, we'll be using the `requests` module to make HTTP requests.

Use the following command to install the `Flask`, `requests`, and `pyngrok` modules:


```shell
pip install Flask requests pyngrok
```

### Create your file

In your project folder, create a new file named `app.py`. Populate that file with the provided "app.py" code found on this page.

app.py
#This file is used to start a lightweight webserver to handle incoming faxes. 
from flask import Flask
from flask import request
from pyngrok import ngrok
import requests
import base64

key = "YOUR_access_key"
secret = "YOUR_access_secret"
project_id = "YOUR_project_id"
service_id = "YOUR_service_id"

app = Flask(__name__)

http_tunnel = ngrok.connect(5000)

url = "https://fax.api.sinch.com/v3/projects/" + project_id + "/services/" + service_id

payload = {
    "incomingWebhookUrl": http_tunnel.public_url,
    "webhookContentType": 'application/json'
}

headers = {
    "Content-Type": "application/json"
    }

response = requests.patch(url, json=payload, headers=headers, auth=(key, secret))

print(response)

print("Your callback URL has been set to " + http_tunnel.public_url)

@app.route('/', methods=['POST'])
def result():
    req = request.get_json()
    base64_bytes = base64.b64decode(req['file'], validate=True)
    if req['event'] == "INCOMING_FAX":
        with open(req['fax']['id'] + ".pdf", "wb") as file1:
            file1.write(base64_bytes)
    return "200 OK"
This code starts your webserver, creates an ngrok tunnel, updates your incoming webhook URL, and also contains the logic to download fax content from the Sinch servers. We'll come back to what those things are in a moment.

Before you save your file and start your server, there's a couple of values you to need to update.

### Update your parameter values

Update the values of the following parameters:

| Parameter | Your value |
|  --- | --- |
| `YOUR_access_key` | The key found on your Sinch [dashboard](https://dashboard.sinch.com/account/access-keys). |
| `YOUR_access_secret` | The secret found on your Sinch [dashboard](https://dashboard.sinch.com/account/access-keys). **Note:** Access secrets are only available during initial key creation. |
| `YOUR_project_id` | The project ID found on your Sinch [dashboard](https://dashboard.sinch.com/account/access-keys). |
| `YOUR_service_id` | The service ID found on your Sinch [dashboard](https://dashboard.sinch.com/fax/services). |


## Start your server

At this point, you can start your server with the following command:


```shell
flask run
```

You should notice a few things.

- First, your console should show that the server has started on port 5000 of your localhost.
- Second, the ngrok tunnel has started and you should see the URL displayed in the console.
- Additionally, you should see a message in your console that the incoming webhook URL for your fax service was updated automatically. There is code in the sample that makes a [request to the Fax API](/docs/fax/api-reference/fax/services/updateservice) to update the incoming webhook URL.


Tip:
You can also update your incoming webhook URL in the dashboard yourself. Navigate to your fax services on your [dashboard](https://dashboard.sinch.com/fax/services). Next to your service click the **Edit** button. You'll see a field labeled "Incoming webhook URL." Enter your URL into that field and click **Save**.

Now your server is listening and your incoming webhook URL is configured, so you're almost ready to test everything and send a fax that you can receive. But before we do, let's take a closer look at webhooks. If you already know about webhooks, skip right to [sending yourself a fax](#call-your-sinch-phone-number).

### Understanding webhooks

Webhooks (also known as "callbacks" or "notifications") are the method that the Fax API uses to inform you when your Sinch number is sent a fax. Basically, a [notification](/docs/fax/api-reference/fax/notifications) is a request that the Sinch servers send to your server whenever something happens (otherwise known as an "event"), such as when you send or receive a fax. There are two different kinds of events, the Fax Completed and the Incoming Fax event, but the one we're concerned about is the Incoming Fax event.

An *Incoming Fax* event happens whenever someone sends a fax to one of your Sinch numbers. All of the notification events the Fax API sends expect a 200 OK response in return.

And that's it! Now we can test.

## Send your Sinch number a fax

Using the [app we created in the previous guide](/docs/fax/getting-started/python/send-fax), send a fax to your Sinch number. The fax should be picked up by the Sinch servers and a PDF of your fax will be downloaded to your machine. Now you know how to handle an incoming fax.

## Next steps

Learn more about the Fax API:

- [API specification](/docs/fax/api-reference/fax)