# Incoming fax event

This webhook is triggered when a fax is received on a Sinch number associated with a service. The webhook will contain information about the fax, such as the sender, the recipient, and the content of the fax. You set the callback URL for incoming fax events on the service, either through the dashboard or using the service API.

### Example payloads

Multipart/form-data request payloads are encoded as forms with a content type of JSON and the actual fax content as a 'file' application/pdf attachment.

Application/json request payloads are a JSON object with the file encoded as a base64 string as part of the JSON object.

Endpoint: POST incomingFax
Version: 3.0
Security: WebhookBasicAuth

## Request fields (multipart/form-data):

  - `event` (string)
    The value is always INCOMING_FAX for this event.
    Enum: "INCOMING_FAX", "FAX_COMPLETED"

  - `file` (string)
    The fax content as a PDF attachment to the body

  - `eventTime` (string)
    Time of the event.

  - `fax` (object)

  - `fax.from` (string)
    For INBOUND faxes, this is the number where the fax is sent from
For OUTBOUND faxes, this is the Sinch number you want to have as sender
    Example: "+15551235656"

  - `fax.to` (string)
    For INBOUND faxes, this is the Sinch number someone sent the fax to.
For OUTBOUND faxes, this is the phone number you want to send a fax to.

You can add multiple numbers by adding them as an array. For example:

  application/json

  json
  "to": ["+14155552222", "+14155553333"]
  

  multipart/form
  json
  to=+14155552222&to=+14155553333
    Example: "+15551235656"

  - `fax.contentUrl` (any)
    Give us any URL on the Internet (including ones with basic authentication)
At least one file or contentUrl parameter is required.
Please note: If you are passing fax a secure URL (starting with https://), make sure that your SSL certificate (including your intermediate cert, if you have one) is installed properly, valid, and up-to-date.
If the file parameter is specified as well, content from URLs will be rendered before content from files.

You can add multiple URLs by adding them as an array them with a comma when posting as multipart/form-data

For example: "https://developers.sinch.com/fax/fax.pdf, https://developers.sinch.com/" or if posting JSON "contentUrl": ["https://developers.sinch.com/fax/fax.pdf", "https://developers.sinch.com/"]
    Example: "https://developers.sinch.com/fax/fax.pdf"

  - `fax.headerText` (string)
    Text that will be displayed at the top of each page of the fax. 50 characters maximum. Default header text is "-". Note that the header is not applied until the fax is transmitted, so it will not appear on fax PDFs or thumbnails.

  - `fax.headerPageNumbers` (boolean)
    If true, page numbers will be displayed in the header. Default is true.

  - `fax.headerTimeZone` (string)
    A [TZ database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) string specifying the timezone for the header timestamp.

  - `fax.retryDelaySeconds` (integer)
    The number of seconds to wait between retries if the fax is not yet completed.

  - `fax.labels` (object)
    You can use this to attach labels to your call that you can use in your BI solutions.
    Example: {"use-case":"fraudPrevention","costCenter":"sales"}

  - `fax.callbackUrl` (string)
    The URL to which a callback will be sent when the fax is completed. The callback will be sent as a POST request with a JSON body. The callback will be sent to the URL specified in the callbackUrl parameter, if provided, otherwise it will be sent to the URL specified in the callbackUrl field of the Fax Service object.

Note: If a callback URL uses basicauth credentials, when the callback URL is retrieved those credentials are masked. It is not possible to retrieve previously-set credentials through the API.
    Example: "https://www.my-website.com/callback"

  - `fax.callbackUrlContentType` (string)
    The content type of the callback.
    Enum: "multipart/form-data", "application/json"

  - `fax.imageConversionMethod` (string)
    Determines how documents are converted to black and white on OUTBOUND faxes only.  Image conversion is not done on INBOUND faxes. Defaults to value selected on Fax Service object.
    Enum: "HALFTONE", "MONOCHROME"

  - `fax.maxRetries` (integer)
    | The number of times the fax will be retired before cancel. Default value is set in your fax service.
| The maximum number of retries is 5.

  - `fax.resolution` (string)
    The resolution for the fax. If this is set at the service, this applies to all faxes sent using that service. If this is set on the fax, this will override the service setting.
    Enum: "FINE", "SUPERFINE"

  - `fax.coverPageId` (string)
    The cover page id you want to use for the fax

  - `fax.coverPageData` (object)
    You can use this to specify custom data for your cover page that will be sent as part of the fax. It is a key value store. Read more about how to use this [here](https://developers.sinch.com/docs/fax/api-reference/fax/cover-pages/). All keys used must be lower case.

- application/json format: "coverPageData": {"customfield1":"customdata1"}
- multipart/form-data format: coverPageData[customfield1] = customdata1

  - `fax.inProgressNotifications` (boolean)
    If set to true, you will receive a webhook notification for each page sent on an outbound fax.

  - `fax.serviceId` (string)
    ID of the fax service used.
    Example: "01GVRB50KEQFFE1SGMPFRNBG6J"


## Response 200 fields