About Webhooks

#Overview

WP Fusion syncs data to your CRM automatically as profiles are updated in WordPress.

However, you may want to trigger an automatic sync of data back from your CRM to WordPress. For example if a user’s custom fields or tags have changed, or if you want to import a new WordPress user from a CRM contact record.

A “webhook” is a small piece of data sent from your CRM to WP Fusion, letting it know that a contact has been edited and the changes need to be loaded back to WordPress.

Webhooks work with most of our supported platforms, for a full list please see the CRM compatibility table.

#How a webhook is structured

A webhook is a URL to your site, followed by several URL parameters. Those are:

• wpf_action (required): This tells your site that the webhook is meant for WP Fusion. The action can be update_tags, update, or add (for more details see below).
• access_key (required): This is the access key from the bottom of the General tab in the WP Fusion settings. This authenticates the webhook.
• contact_id (sometimes required): Depending on your CRM, you may need to include a contact ID in the webhook URL to tell WP Fusion which contact to load. Please refer to the documentation for your CRM (see the sidebar navigation) for an example.
• role (optional): When using the add or update method, you can specify a role for the user by setting the role query parameter.
• send_notification (optional): When using the add method, setting send_notification=true will send a welcome email to the new user with a link to set their password.

You can test a webhook for a specific content by visiting the URL in your browser. For example https://mysite.com/?wpf_action=add&access_key=KEY&contact_id=123

#Webhook strategy

While it’s tempting to want to keep everything in sync all the time, it’s also important to keep in mind that processing webhooks requires a fair bit of server resources.

When a webhook is received, WP Fusion needs to connect back to your CRM, load any updated data, save it, and trigger any automated enrollments. This process takes a few seconds to run.

For example, if you’ve configured your webhooks to sync every contact record edit back to WordPress, and you bulk edit a bunch of contacts in your CRM, you can end up temporarily crashing your website while it struggles to deal with all the webhooks.

That’s why we recommend setting up your webhooks so that they run just when data needs to be loaded back into WordPress. For example when a tag is applied that unlocks a new piece of content (as opposed to whenever any tag is applied).

#Duplicate webhooks

WP Fusion will try to detect when two duplicate webhooks are being received at the same time for the same contact, in order to prevent potential data loss. This will be recorded to the logs with a yellow notice.

If you see messages in the logs regarding duplicate webhooks, please review your webhook setup to make sure that the same webhook can’t be triggered twice for the same contact.

#Loopback webhooks

It’s important to try to avoid triggering a webhook as a result of something changed by WP Fusion, as this can result in potential data loss.

As an example:

1. A customer checks out via WooCommerce and WP Fusion creates a new contact record in your CRM with the customer’s name and email. The contact doesn’t yet have any tags.
2. You’ve configured a webhook back to WP Fusion for any time any contact is edited, and so this new contact meets the condition and the webhook is sent.
3. At the same time, WP Fusion begins to apply the tags that would enroll the new customer into the course they just purchased.
4. The webhook arrives, indicating that a new contact has been updated and has no tags.
5. This erases the tags that were applied in Step 3, and the customer loses access to their course.

In this scenario there’s no reason to send a webhook back to WP Fusion telling it a new contact was created— because WP Fusion is what created that contact. As possible solutions you could make your webhook trigger more specific by requiring a tag, or by checking the contact’s creation date.

If you can’t prevent loopback webhooks (for example Gist always sends a webhook whenever WP Fusion applies a tag over the API), you can try this snippet:

This will “lock” a user for one minute every time a tag is applied. While the user is locked, any incoming webhooks will be blocked for that user.

This is still not ideal for performance, since your site is getting hit with redundant webhooks, but it should prevent unexpected data loss.

#Webhook troubleshooting

Webhooks can sometimes get blocked by your web hosting, or security plugins. For more info, see the Webhooks not being received by WP Fusion documentation.

#How to set up webhooks in your CRM

See the navigation at right for CRM specific tutorials on how to configure webhooks.