The <$BlogConnect$> tag allows you to insert or manipulate content from an external system. Depending on the nature of the web hook called, you can retrieve data from a third party system, or set data on a third party system. It’s a really powerful templating tool which can be used to truly drive personalized, engaging, email communications.

Privacy, PII, and GDPR Compliance

Whenever you call a third party solution, you must be sensitive to the data you are sharing. Bear in mind that web requests are universally logged by all web servers, and so any parameters you pass in a URL will end up in a web server’s log somewhere. You should behave as if that log will be made public at some point, which will in turn risk privacy violations if you have not been careful.

Terms of Service

IMPORTANT: The list of Dos and Don’ts below is not intended to be exhaustive; it is meant as a starting point to spur your thinking.

• FeedBlitz does not guarantee that following these tips will be sufficient to legally protect you.
• FeedBlitz will not indemnify you if you use our services and your third party is compromised.
• You should consult with your own legal, IT security, and compliance resources before using FeedBlitz’s <$BlogConnect$> functionality.

Your use of FeedBlitz’s <$BlogConnect$> functionality is entirely at your own risk,
and covered by FeedBlitz’s terms of service.

Suggestions

• Do
  • Validate that any third party systems you use follow your own privacy policies, FeedBlitz’s privacy policies, and (if necessary) listed in your list of external data processors for GDPR.
  • Send the minimum amount of subscriber information necessary to achieve your goals.
  • Use hashes instead of plaintext PII (personally identifiable information).
• Do Not
  • Base64 encode plaintext PII, such as the subscriber’s email address. Encoding is not the same as encryption.
  • Send enough information to allow a third party to figure out the individual (e.g. do not send birthday, birthdate, or location information)
  • Send confidential information (government supplied identification numbers, financial information, health information)

Tag Syntax

<$BlogConnect url="webhook URL" method="GET or POST" nocache="1" headers="HTTP headers" content-type="MIME type" accept="*/*" uid="HTTP authentication user" pwd="HTTP authentication password" payload="data for a POST" assign="dynamic variable name" fail="error content"$>

Unless the “assign” attribute is used, the retrieved content will replace the whole <$BlogContent$> tag in your message. If the same <$BlogConnect$> tag appears multiple times in your template, all instances will be replaced by the first call to the webhook, successful or otherwise.

You may use custom fields (stored and dynamic) within the tag. If you are using simple functions (e.g. <$foo$> to insert the value of the custom field “foo”), FeedBlitz will automatically URL encode the value prior to calling the webhook.

Required Attributes

url

The URL of the webhook you are calling. You can include custom fields to provide a tailored experience (remembering that you should avoid sending PII). For example, if you want to insert the weather from a hypothetical web service at https://example.com/weather and you have the subscriber’s zip in the custom field “Zip” which the webhook needs in the “postcode” parameter then this is valid:

<$BlogContent url="https://example.com/weather?postcode=<$Zip$>"$>

Of course, there’s absolutely nothing stopping you from storing the URL you want to fetch per subscriber in a FeedBlitz custom field, if that makes sense for your use case, in which case the tag would look something like this:

<$BlogContent url="<$WebHookURL$>"$>

If you want a unique result per subscriber but don’t want to risk PII disclosure, since the FeedBlitz subscriber ID is just an opaque number, you can do this:

<$BlogContent url="https://example.com/weather?postcode=<$Zip$>&foruser=<$BlogRecipientID$>"$>

If you need to send a hash of the recipient’s email to your webhook, you should use one of the intrinsic hashing functions. If you need to send a salted hash, you can use the string functions to construct the salted data before you hash it.

If you specify an attribute, but give it no value, the default will be used. If you specify an attribute not listed here, FeedBlitz will ignore it.

Optional Attributes

method

GET or POST. Case insensitive. Default: GET

nocache

Default value: 0

FeedBlitz will attempt to cache and reuse results from the webhook if the following conditions are all true:

• GET method
• No custom fields within the <$BlogConnect$> tag
• The nocache attribute is 0

Setting this to a non-zero number prevents FeedBlitz from re-using the results of the call. However: Doing this can be perceived as being hostile by the remote site, which might react unkindly to thousands of more or less simultaneous requests. If your use case allows caching, you should work to ensure FeedBlitz can cache the webhook. See the caching section below for more.

If a third party site complains to FeedBlitz about webhook usage, FeedBlitz may disable or rate limit your use of the functionality.

headers

If your webhook needs custom HTTP headers, specify them here. If you need to specify multiple headers, use the vertical bar (pipe) character to separate them in the tag, as in:

headers="X-foo: ABC|X-bar: PQRS,q=0.7"

content-type

Used by POST only, default: application/x-www-form-urlencoded

If you need to specify a different MIME type for your POSTed payload, specify it here.

accept

Default: application/json, text/plain, text/html, text/*, */*”

The default should work for most use cases but you may override it if necessary.

uid

The webhook can provide HTTP basic authentication credentials. There is no default, specify the required user id here.

Important: It is generally considered poor security to provide security credentials in plaintext, which this requires you to do. You can of course store the data in a custom field. Assuming user id and password are account wise, when defining the field give it the default of the required value, and ensure it is a hidden field, which makes it invisible to subscribers.

pwd

The webhook can provide HTTP basic authentication credentials. There is no default, specify the required password here.

Important: It is generally considered poor security to provide security credentials in plaintext, which this requires you to do. You can of course store the data in a custom field. Assuming user id and password are account wise, when defining the field give it the default of the required value, and ensure it is a hidden field, which makes it invisible to subscribers.

payload

default: none

For POSTs, specify the data to send. You may construct it from custom field data in the FeedBlitz database, or dynamic fields created within the template.

assign

default: none

Instead of inserting the result of the webhook directly into the email, you can assign it to a custom field for the duration of the template processing here. In particular, you can create a new dynamic field here, which you can then later reference – and, if it’s JSON, parse and access.

For example, setting assign="tempvar" in the tag creates the custom field called “tempvar” and assigns to it the content returned by the webhook. You can use that variable in other template functions, or – if it’s JSON – de-reference it.

For example, if the JSON returned is a five element array, then:

• tempvar.length is 5.
• tempvar[1] is the second element in the array.
• <$tempvar$> will insert the entire JSON object into into the message

fail

Default: blank (i.e. fail silently)

In case the webhook fails or times out (see the caching section below), insert this content instead of an error message or technical content that might confuse a less technically sophisticated reader if it appeared in a message from you. As the default is blank, the result is that the hook fails silently without adding error messages to the message.

if you really want to see the error message, say during testing, set this attribute’s value to be the string “Err.Response” as in fail="Err.Response"

Caching (or, Being a Good Internet Citizen)

By default, FeedBlitz will attempt to cache both the call and its results. This ensures the fastest possible mailing and the kindest possible mailing (to the remote site, at least, particularly in terms of bandwidth and CPU usage). What you really want to avoid looking like is a DDOS (distributed denial of service) attack from FeedBlitz on the destination site. FeedBlitz would like to avoid being looked at that way too!

So, you should cache. This means that you should:

• Use GET, and
• Not use variables in the BlogConnect url, and
• Not specify nocache with a non-zero value.

For truly personalized content, of course, that simply won’t work – the content will be unique per recipient, and that means a unique <$BlogConnect$> tag. To minimize the risk of being confused as driving hostile content, then, we recommend:

• Only using non-cacheable <$BlogConnect$> in transactional mailings, not bulk mailings.
• If bulk mailings with this tag are unavoidable:
  • Shape the mailing with a group or other criteria to reduce the number of emails sent.
  • Use <$if$> to avoid the call if you know it won’t apply to the current recipient.
  • For broadcast mailings, use a paced mailing to spread the load over time (FeedBlitz’s default is “as fast as possible” – you may be required to upgrade as this paced mailings are an Accel / Enterprise capability)
  • Avoid the tag altogether: If the data isn’t particularly dynamic, store the results you need in a custom field, then sync them up when necessary via an import, or using a middleware service like Zapier.
• Regardless, let the third party service (or your IT function, if the URL is for an internal system of yours) know that this is happening so that they can expect it and plan accordingly (even if that plan is “ignore all these requests”).

Finally, FYI, know that the FeedBlitz user agent for these requests specifies that it is for a webhook, and will list your List ID along with information on how to contact FeedBlitz support. No PII about you is shared, but FeedBlitz will be able to tie webhook behavior that upsets third parties back to your account if necessary.

Performance Requirements

FeedBlitz requires that the webhook you specify respond within two seconds, otherwise the call will time out. In that event, FeedBlitz will immediately retry, exactly once. If the failure continues, the content specified in the “fail” attribute will be used. To reduce this risk, try to use cacheable webhook calls wherever possible (see the discussion in the above section).

Third Party Rate Limits

You may find that your use of third party sites and services via the <$BlogConnect$> is rate limited or even blocked by those sites. FeedBlitz is not responsible for how third party services react to your usage via this tag. You may be required to register with the third party, upgrade your account with them, abandon (or scale back) your usage, or pace your mailings. A mailing giving unexpected content because a third party dislikes your usage is not FeedBlitz’s issue, and not ours to solve – it is between you and the the third party.

That is unless that third party decides to block or rate limit FeedBlitz, or any of our servers, as a whole. In which case FeedBlitz will take action to protect ourselves and our clients, up to and including requiring you to upgrade to a different FeedBlitz plan to enable succesful mitigation, or closing your account. Remember, FeedBlitz’s terms of service always, always apply.

Testing your <$BlogConnect$> call

• Test by using FeedBlitz’s test emails to send yourself test mailings containing the <$BlogConnect$> tag first.
• Test error handling in the message by calling a URL that doesn’t exist or you know will fail.
• Test by sending test mailings using a larger group of accounts to validate cross-subscriber success
• Test by sending a bulk mailing to a seed list or group to validate cross-subscriber success under load.
• Talk to your legal, IT, and / or compliance departments if necessary.
• Talk to the third party site if you do not control, or have an existing relationship with it.
• Gradually move into production.