Using webhooks

How to use GoFax webhooks in combination with the API to develop an integration.

GoFax can be configured to trigger a webhook when a fax or SMS is sent or when a fax is received. 

When building your integration, we highly recommend that you consider implementing an event based architecture using webhooks.

These notifications are simply HTTP POST requests with form-data (URL encoded metadata). 

Basic Authentication (base64 encoded auth header) is supported and configurable as described below.

Fax send

To configure fax send notification URL: 

1. Log in to your GoFax secure web portal
2. Select -> Send Fax Service -> Manage Send Settings -> General Fax Settings 
3. Enter details.
   E.g.:

This can also be configured programmatically using the API endpoint PUT /v1.0/SendFax/Settings

You may also include a "callbackUrl" when submitting a transactional fax job via the API. See example request body to PUT /v1.0/SendFax :

{
   "SendTo":"61711111111", //Recipient fax number
   "Documents": 
   [ 
    {
      "Filename":"My File.pdf",
      "Data": "<base64 encoded fax document>"
   ],
   "CallbackURL":"https://webhook.company.com"
}

Contents

Once a fax transmission has reached a final status (see Fax send status codes), a POST request with the following form-data will be sent to your configured webhook.

Example URL encoded event data for a successfully sent fax:

Recipient=61712344321&ID=41340078&Success=True&Message=Fax+successfully+sent&Subject=Email+to+Fax

We recommend storing this data, especially the "ID" such that your integration can query further details using relevant API endpoints (see our Swagger UI). 

SMS send

To configure SMS send notification URL: 

1. Log in to your GoFax secure web portal
2. Select -> Send SMS Service -> Manage SMS Settings -> General SMS Settings
3. Enter details.
   E.g.:

Contents

As with fax, when an SMS job reaches a final state, a webhook is triggered.

Example URL encoded event data for a successfully delivered SMS message:

Recipient=61412121212&ID=52410901&Success=True&Message=Message+successfully+delivered

Again, we would recommend storing the "ID" to gather further meta-data using other SMS API endpoints. 

Fax receive

To configure receive fax notification url: 

1. Log in to your GoFax secure web portal
2. Select -> My Account  -> Account Details 
3. Enter details.
   E.g.:

This can be programmatically configured using the PUT /v1.0/Account/Details 

Contents

When a new fax is received, GoFax will push a web notification to the configured URL. The webhook data is as follows:

Example of the form-data for a received fax:

FaxID=4851543&Number=61712344321&Message=COMPLETE&SenderFaxID=0311223344&SenderISDNID=0311223344&TransmissionTime=24&NumberOfPages=1&TransmissionSpeed=33600

You can use the "FaxID" value with the API endpoint GET /v1.0/ReceiveFax/{faxId}/Document to download the received fax file in base64 encoded format.