Starting integration

This section describes the various ways to integrate press release feed found at https://mfn.se/s onto a third party platform. When an integration has been setup, MFN pushes press releases to your platform at the same time they are published to the markets.

MFN provides various integration methods with respect to transport protocols and content format. This enables you to select a configuration that best suits you. Regardless of configuration, every distributed press release uses MFN's News Item model, see News Item.

MFN also provides multiple filters so that you can subscribe to a subset of press releases matching your interests.

Content-Types

• JSON

• XML

The easiest ways to get to know the different content-types / formats is to inspect feeds listed below:

• https://mfn.se/s

• https://mfn.se/s.json

• https://mfn.se/s.xml

Transport

• HTTPS

• SFTP

Selecting a Configuration

This will, of course, depend on your company's conditions. The content type is agnostic to the selected transport, so pick the content type that best suits your conditions.

Our suggestion is to go with HTTPS and JSON as it is a simple solution that works well and is easy to setup.

Inform us if you want to apply any filtering. For example: specific language, country, regulatory, etc.

Provide us with a secret. The secret is a sequence of alphanumeric characters that enables you to verify the integrity of received press releases, see Verifying Press Releases (HMAC Verification).

Regardless of chosen transport, you should consider the following:

• You may receive many requests, in parallel, within a short span of time.

• A request always contains a single press release.

• De-duplication of press releases.

• MFN will re-try transfers up to five times if unsuccesful.

HTTPS

HTTP/HTTPS endpoint hosted on your server for receiving press releases.

Requirements:

• An endpoint that supports POST requests to be able to receive press releases. The endpoint should preferably be hosted on a "hard to guess" path, e.g.: https://company.com/api/post-hook/kliyslj1am, to minimize the risk of malicious entities trying to inject press releases onto your platform. SeeVerifying Press Releases (HMAC Verification) for another solution.

• Handle that the request body contains a News Item in JSON (or XML) format.

• Respond with the HTTP status 200 if you correctly received the release. This tells our backend that it doesn't have to retry the request.

SFTP

SFTP server hosted by you to receive press releases.

The filename MFN uploads by default follows this schema:

• mfn_<slug>_<news_id>.<extension>

• <slug>: String of varying length

• <news_id>: An UUID, e.g. 88e76183-a98d-5573-a9e8-392c0ecdd355

• <extension>: Extension matching your selected content type, i.e. json or xml

The filenames can be tweaked, depending on your requirements. For example so that filenames do not become too long for your SFTP-server's file system.

Requirements:

• Host that MFN should upload files to

• User account for MFN

  • Authentication details: password or public key

Also, let us know if the SFTP-server has any technical limitations, e.g.

• Limit on number of concurrent uploads to your SFTP

• File size limits

HMAC Verification with SFTP

Headers are transferred in an additional file, since request headers are not available as in HTTPS. The extra file is named <filename>.headers . It contains key-value pairs as HTTP headers does, see below:

... 
X-Hub-Signature: sha256=2b2fdc7606cbe9e8ab2327cf8de569977aad0895aa36e69a40a881ea907be2e2
...

Verifying Press Releases (HMAC Verification)

This section is voluntary, but highly recommended.

MFN calculates a hash given a press release and a secret and sends the hash together with the press release. Since MFN and you are the only two entities that know the secret, you can compute the hash with the secret and the received press release. Verifying that the hashes are equal guarantees that no malicious third party has tampered with the press release during its transmission over the internet.

Using the secret you provided us with when you setup the subscription, you can verify the received request content by the following algorithm (pseudo code). Note the sha256-hash algorithm. Assuming HTTPS transport which sends the hash in the X-Hub-Signature header

received_hmac_sig = http_request.headers().get("X-Hub-Signature")
calced_hmac_sig = hmac_sha256.calc_sig(hub_secret, http_request.body())

if received_hmac_sig == calced_hmac_sig:
  // SUCCESS
  persist(http_request.body())
  return 200 // this signals to use that we don't need to retry this request
else:
  // MALFORMED REQUEST
  return non-200 http status back to use to signal error, can include error msg

Whitelisting MFN's IP Addresses

Let us know if you require MFN to transfer press releases to you via static IP addresses for whitelisting purposes.

Alternatives

While we strongly recommend the approaches described in this guide, we are always open for discussion and can be flexible if the recommended integrations does not work for you. Contact us for more information about other options and solutions.