Handle an incoming fax with .NET

Now that you know how to send yourself a fax a using the Fax API, learn how to handle incoming faxes.

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.
• .NET 6.0 or later SDK and .NET Runtime and a familiarity with how to create an app.
• ngrok and a familiarity with how to start a network tunnel. You can use any method you want to make your server accessible over the internet, but we like ngrok and it's what we'll use in this guide.

Set up your .NET application

Create a new project folder and open a command prompt. Execute the following command to create a new .NET web application:

dotnet new web

This creates a new web application and project.

Set up your file

1. In your project folder, open the Program.cs file and paste the following code into the file, replacing all the existing content:
   Copy

   Copied

   using Microsoft.AspNetCore.Mvc;
   using ReceiveFax;
   
   var builder = WebApplication.CreateBuilder(args);
   var app = builder.Build();
   
   app.MapPost("/", ([FromBody]IncomingFaxEvent incomingFax) => IncomingFax.ReceiveFax(incomingFax));
   app.Run();

   This code starts your webserver and sets up the POST mapping.

2. Next, create a new file in the project named IncomingFax.cs, and paste the IncomingFax.cs code from this page into the file.

This file contains the logic to download fax content from the Sinch servers.

Start your server

You can start your webserver by running the following command:

dotnet run

Take note of which port on which your server is running.

Start your ngrok tunnel

At this point you need to start your ngrok tunnel so that the Sinch servers can access the webserver running on your local machine. Run the following command to start your tunnel:

ngrok http [PORT]

Copy the http ngrok URL. Navigate to your Fax service on your dashboard. Select your default service and click Edit. You'll see a field labeled "Incoming webhook URL." Paste your ngrok 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.

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 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, 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