The UGC + Community API

In this article, we will cover:

• Overview
• How to add a Webhook
  • Available Events to Listen To
  • Filter Events with Conditions
• Configure Advanced Webhook Options
  • Set the HTTP Verb
  • Add Headers
  • Customize the Body
  • Trim or Expand the Payload via the API
  • Test Your Webhook
  • Limitations
• How to create an OAuth Application
• How to get the Client ID and Secret ID for the OAuth Application
• Get an Access Token (Authorization Code Flow)

Overview

The UGC + Community API is a RESTful API that allows you to interact with the platform's data and features. It is built on HTTP, uses the OAuth 2.0 protocol to authorize applications to access data on behalf of the user, and requests and responses are formatted in JSON:API specification.
The UGC + Community API provides a variety of endpoints that allow you to do things like:

• Create, update, and delete Boards
• Manage users
• Manage teams
• Insights into your Boards
• And much more

The UGC + Community API is a powerful tool that can be used to automate tasks, keep your data up-to-date, and integrate with other applications. If you are looking for a way to get more out of the platform, then our API is definitely the way to go.

For complete documentation on our API, please reference our developer docs, found here.

Note: Who can create, edit, or delete webhooks and OAuth applications is controlled by role permissions, so a team administrator can decide which teammates have access. See Roles and Collaborators for how to assign these.

How to add a Webhook

1. Click on Global Settings in the left side navigation panel
2. Click on API and navigate to Webhooks
3. Click on + Add button next to the WebHooks header
4. This will open a pop-up box.  For this, you will need an ENDPOINT URL as standard.  The optional items are Shared Secret and a description of the Webhook.
5. Then you will select SELECT EVENTS TO LISTEN TO: from the list 
6. Click on Apply
7. This will put your Webhook in the list

Tip: If you don't have a shared secret yet, you can generate a random one with this command:

openssl rand -hex 32

Available Events to Listen To

The Event to Listen To list includes the following options:

• Account Created
• Account Updated
• Account Destroyed
• Asset Created
• Asset Updated
• Asset Destroyed
• Asset Exported
• Form Submission Created
• Form Submission Exported
• Post Created
• Post Updated
• Post Destroyed
• Post Exported
• Product Feed Created
• Product Feed Updated
• Product Feed Destroyed
• Transaction Exported
• Collaborator Exported
• Member Created
• Member Updated
• Member Destroyed
• Mission Created
• Mission Updated
• Mission Destroyed
• Offer Created
• Offer Updated
• Offer Destroyed

Filter Events with Conditions

After selecting an event to listen to, expand Conditions to limit which instances of that event actually trigger the webhook. For example, you can limit a Form Submission Created webhook to a specific form instead of firing for every form on the account.

1. In the Type variable field, enter the attribute key to check.
2. Choose the operator. Conditions currently support Equals only.
3. Enter the Value to match.
4. Click Add Condition if you need to check more than one condition.

Note: Condition field names (the Type variable value) must match a key inside the attributes of that event's regular webhook payload. Each condition needs a different Type variable, adding two conditions on the same variable returns a "Variable names must be unique" error.

Configure Advanced Webhook Options

When you create or edit a webhook, you can expand Advanced Options to customize the request. Every setting in this section is optional, you can change one and leave the rest at their defaults.

Note: Advanced Options are only available once the webhooks_advanced feature is enabled for your account. If you don't see this section, contact your TrueLoyal team to turn it on.

Set the HTTP Verb

The HTTP Verb defaults to POST. If the receiving system expects a different method, select it from the list. For example, if your system expects a DELETE request when a member is deleted in TrueLoyal, select DELETE.

Add Headers

To add a header, click Add Header, and then enter the header name and value. You can add as many headers as the destination needs. Here are two common ones:

• Authorization: Bearer YOUR_API_KEY, authenticates the request. Replace YOUR_API_KEY with the key from the receiving system.
• Content-Type: application/json, tells the destination the payload is JSON.

Note: Header values are fixed, so they work well for static API keys. If the destination uses OAuth access tokens that expire, you'll need a separate service to refresh the token, the webhook itself can't refresh it for you.

Customize the Body

The Body field controls the payload that TrueLoyal sends. If you leave it blank, TrueLoyal sends its default payload for the event. To shape the payload to match what the receiving system expects, you can write a template in Liquid, a templating language used across many web platforms. Liquid supports variables, conditions such as if statements, and other logic, so you can decide what to send based on the data itself, in addition to renaming fields.

For example, the following template builds a small payload when a new account is created:

{
  "email": "{{ data.attributes.email }}",
  "first_name": "{{ data.attributes.first_name }}",
  {% if data.attributes.tier %}"tier": "{{ data.attributes.tier }}",{% endif %}
  "source": "trueloyal"
}

This template pulls the member's email address and first name from the account record, checks whether the member has a tier and only adds a tier field if they do (so the receiving system never gets an empty or null value it doesn't expect), and adds a fixed source field set to trueloyal so the receiving system knows where the data came from.

Trim or Expand the Payload via the API

If you're configuring a webhook directly through our API rather than through Advanced Options in the UI, you can also reduce what's included in our regular payload, or augment it with additional related resources, instead of writing a full Liquid template. See the webhooks endpoint reference in our developer docs for the exact parameters.

Test Your Webhook

To test a webhook, point it at a free request inspection tool such as webhook.site, trigger the event, and review the payload that TrueLoyal sends.

Limitations

• Header values are static, webhooks can't refresh expiring OAuth tokens.
• Each webhook listens to one event. To send several events, create a webhook for each one.
• Event filter conditions (see Filter Events with Conditions above) currently support equality only.

How to create an OAuth Application

1. Click on Global Settings in the left side navigation panel
2. Click on API and scroll down to OAuth Applications
3. Click on + Add button next to the OAuth Applications header
4. This will open a pop-up box. For this, you will need a DISPLAY NAME and REDIRECT URI
5. Click Create
6. Your OAuth Application will then appear in the list. To retrieve your Client ID and Secret ID, click the dropdown arrow and enter your password to reveal the Secret ID.

How to get the Client and Secret ID for the OAuth Application

1. To open the information, click on the dropdown arrow on the OAuth Application you want to see the Client and Secret ID for
2. The Client ID is already visible.  To get the Secret ID, click on Show
3. This will then ask you for your password, enter this and click Confirm Password
4. Then your Secret ID will be visible for you to copy as well

Get an Access Token (Authorization Code Flow)

Once you have a Client ID, Client Secret, and Redirect URI, you can use the authorization code flow to get an access token. This flow needs a person to log in and approve access interactively, so it suits integrations where a user is in the loop, rather than a fully unattended server-to-server job.

1. Send the person to TrueLoyal's authorization URL, including your Client ID, Redirect URI, response_type=code, and the scope(s) your integration needs.
2. After they log in and approve access, TrueLoyal redirects them back to your Redirect URI with a code in the query string.
3. Exchange that code for an access token and a refresh token by calling the token endpoint with your Client ID, Client Secret, and the code.
4. When the access token expires, use the refresh token to get a new one without asking the person to log in again.

See our developer docs for the exact request and response format, and the full list of available scopes.

Note: This flow needs a person to authorize interactively. If your integration runs fully unattended with no user in the loop, talk to your TrueLoyal team about the best way to set it up.

If you have any questions regarding the UGC + Community API, please don't hesitate to contact Technical Support at support@trueloyal.com.