For applications that process protected health information (PHI) or other sensitive data, it is a good practice to verify
that callback requests are in fact coming from Phaxio servers and not a malicious third party.
Due to the autoscaling nature of the clusters that perform callback requests, Phaxio does not publish an IP whitelist that can be used to restrict
incoming traffic in your firewall. Instead you can use HTTP Authentication or the X-Phaxio-Signature header
to secure your application for callbacks.
Additionally, we recommend that all callback URLs provided to Phaxio use TLS.
You can provide a username and password in your callback URL and Phaxio will use these credentials when making requests.
For example, for a URL https://example.com/phaxio/callbacks with username foo and password bar, you can pass Phaxio
a URL in the following format and Phaxio will call it with HTTP authentication headers:
Callback tokens and X-Phaxio-Signature header
Every callback request contains a X-Phaxio-Signature header that can be used to verify the request. Phaxio generates a
string that describes the content of the request and signs it using your account’s unique callback token. Your callback token
can be found on your Callbacks Settings page. To validate a request your application
can recreate the signature and compare it to the X-Phaxio-Signature header.
To generate the signature:
Take the URL string that you’ve submitted to Phaxio, including any trailing slashes.
Sort all POST parameters by name.
For each POST parameter, concatenate its name and value without any delimiters to the URL in step 1.
Sort any file parts in the request by name.
For each file part, concatenate its part name and SHA1 digest of its file contents to the resulting string in step 2.
Sign the resulting string with HMAC-SHA1 using your Callback Token as the key.
Most official Phaxio client libraries contain helper functions for generating callback signatures. Additionally, here
are some code examples that can be used to validate requests.