HomeGuidesAPI Reference
Submit Documentation FeedbackJoin Developer CommunityOptimizely GitHubOptimizely NuGetLog In

Open API introduction

This is the Welcome Open API and Webhooks developer guide. See also the following documentation:

Base URL: https://api.welcomesoftware.com/v3

📘

Note

The open API is served through https://api.welcomesoftware.com/v3. We encourage to update your integrations to use the new base URL. The previous base URL: https://api.welcomesoftware.com/v3 will remain functional as it used to be until any further notice.

Welcome provides customers with access to a public API so that they can integrate their own applications for a wide variety of awesome automations! This article will take you through the basic concepts of integrating an application with Welcome using our API and Webhooks, the resources we have provided to help developers achieve success in their development endeavors, and the precise steps you’ll need to get started. 

What can the Welcome Open API and Webhooks do for me?

Welcome's library of API's and Webhooks are designed to help you achieve integration with other applications in your MarTech ecosystem. Our customers and partners have used the Open API and Webhooks to achieve some of the following as good examples:

Asset API and Webhooks (Library) - Asset Synchronization

  • The Asset API can be used to synchronize assets (all supported asset types in Welcome) in the Welcome Library with a DAM. The Asset API can also synchronize asset metadata between two systems.
  • The Asset API can be used to send approved images from the Welcome Library to a specific folder in an image repository.
  • The Asset API can be used to synchronize assets with a Sales Enablement or Marketing Automation platform as well. This includes the metadata needed to sort, organize, and target those assets to specialized audiences in those systems.

Task API - External Work Management

  • The Task API can be used to establish a link between a task step in Welcome and a request 'ticket' in another system. The link can then be used to allow a Welcome user to monitor the progress of the 'ticket' as it progresses through an external workflow. 
  • The Task API can also be used to allow users to collaborate during a workflow step with users in an external system during the content creation process.
  • The Task API can be used to defer a Welcome workflow step approval to an external system for the purposes of more complex Legal reviews and compliance.

For more information on the Welcome Open API, please visit developers.newscred.com.

Who uses the Welcome Open API and Webhooks?

This article is intended to help developers get started with their development research. This article may also be helpful for others who are participating in the research of integrating applications with Welcome. This might include the following types of team members:

  • Developers and System Architects
  • Product Owners/Managers for integrations
  • Members of the IT team supporting the Welcome team at your organization
  • Technical leaders who are estimating the effort and feasibility of custom integrations

Glossary & Integration Concepts

Let’s start with some terms that you’ll hear from us quite often when it comes to integration!

  • Public or Open API - These terms refer to the features of our product which are exposed for other systems to consume. The manner in which they connect to Welcome is achieved via an API which is documented at developers.newscred.com.
  • Webhooks - This term refers to the library of events to which other systems can subscribe to be notified programmatically. For example, when an asset is added to the library, a Webhook makes sure that another system can subscribe to and listen for that activity.
  • Client Application - This term refers to a web application which sits outside of Welcome and receives API messages from the Welcome API’s and Webhooks.
  • Native Integration - Welcome offers a number of available integrations today via native, or Out-of-the-Box integrations. These include Facebook, YouTube, LinkedIn, among others. These are integrations that are maintained by Welcome and are configured in the platform.
  • Custom Integration - A custom integration is an integration that is built and maintained by a third party. That third party could be an agency, a partner of Welcome, or you, our customers. Welcome’s Public API and Welcome’s Feed API are two tools which help make custom integrations possible.

What do you need to be successful using Welcome’s API and Webhooks?

To get started building your own custom integration with Welcome, there are a few things that will help you be successful. Among them are:

  • Knowledge of REST
  • Knowledge of JSON
  • Access to the Welcome CMP Platform
  • A Client Application - that is, the application that will connect to Welcome as a client and consume the API and Webhooks

Get started

Now that you have some of the basics covered, you’re ready to begin integrating your applications.

Welcome’s Open API uses the widely accepted industry standard, OAuth2, as the authentication and authorization framework. This means essentially that your client application will be required to follow the conventions outlined by the Internet Engineering Task Force’s OAuth2 Specification. If you need help with OAuth2 or you suspect your client application will not be eligible to connect via OAuth2, just contact our support team and we’ll be happy to help!

📘

Note

As you begin this process, it would be a good idea to have your client application open and ready so that you can copy and paste the client ID and Secret for immediate testing.

In this article, you will learn how to, 

Acquire Welcome Authorization Information

As you begin developing your client application, you will need some of the following information to get started. This information is also available at developers.newscred.com.

  1. Host: https://accounts.welcomesoftware.com
  2. Authorization endpoint: https://accounts.welcomesoftware.com/o/oauth2/v1/auth
  3. Scopes: openid, profile and offline_access (These scopes are delimited by a single space. All of these scopes must be passed to the authorization endpoint)
  4. Token endpoint: https://accounts.welcomesoftware.com/o/oauth2/v1/token
  5. Userinfo endpoint (can be used to validate access token): https://accounts.welcomsoftware.com/o/oauth2/v1/userinfo

Next, when you’re ready for the client ID and Secret in your application, you’ll be ready to register your app with Welcome. Review the rest of the Authentication and Authorization information available on developers.newscred.com to make sure your client application is ready for the registration process.

Obtain the Client ID and Secret: Register your Client Application 

For performing this step you must have the permission ‘Manage Integrations’ in your role profile. It is highly recommended that you are an Admin. This first step will require you to register your client application so that you can receive your client ID and Secret.

Follow the steps below for obtaining the client ID and Secret. 

1. Access the Settings Menu from your avatar and locate ‘Apps and Webhooks’

Screenshot 2021-12-24 at 12.29.51 AM.pngScreenshot 2021-12-24 at 12.29.51 AM.png

 2. Select ‘Register App’ at the top right on the Apps & Webhooks page. 

Screenshot 2021-12-24 at 12.30.51 AM.pngScreenshot 2021-12-24 at 12.30.51 AM.png

3. Provide the following information about your client application.

Mode:

The client application has two preset modes, 

  1. Development Mode
  2. Production Mode

Screenshot 2021-12-24 at 12.34.54 AM.pngScreenshot 2021-12-24 at 12.34.54 AM.png

If you are developing a client application in a sandbox instance of Welcome, it might be beneficial for you to set the mode of your newly registered application to ‘Development’. This will retain your authentication token for up to 30 days. Once you move your integration into your production instance of Welcome, you’ll want to make sure the mode is set to Production to ensure a more secure timeout. Here are a few other differences between Production and Development Mode:

  Development Mode Production Mode
TTL for the access token 30 days 1 hour
Rate limit 20 requests per minute 20 requests per minute
Request quota 100,000 requests per month 100,000 requests per month

At this time, these modes cannot be changed once an application is registered. If you are making the transition from Development to Production, you can simply register a new application with the same settings.

Name & Description: 

Give your app a friendly purposeful name and provide some additional information about the app in the description box. 

Screenshot 2021-12-24 at 12.35.33 AM.pngScreenshot 2021-12-24 at 12.35.33 AM.png

Expose Email Address: 

If email is exposed, all email addresses will be visible to authorized API responses where applicable. 

Screenshot 2021-12-24 at 12.38.23 AM.pngScreenshot 2021-12-24 at 12.38.23 AM.png

Homepage URL:

Enter the value that represents your application’s homepage. This value represents a URL that can be used to redirect the user should there be any timeout or error conditions during the integration.

Screenshot 2021-12-24 at 12.40.51 AM.pngScreenshot 2021-12-24 at 12.40.51 AM.png

Authorization Callback URL’s

During the OAuth2 exchange, Welcome’s server will send and receive responses to this authorization callback URL. Enter the URL which will receive the authorization requests from the Welcome server. These URL’s should always begin with https://.


4. Select ‘Create App’ after filling all the necessary information about the app. 

Screenshot 2021-12-24 at 12.43.48 AM.pngScreenshot 2021-12-24 at 12.43.48 AM.png

5. After you select ‘Create App,’ you will be taken back to the grid view of all registered applications. Click on your newly created application and ‘Edit’. Two new fields will appear:

Screenshot 2021-12-24 at 12.44.35 AM.pngScreenshot 2021-12-24 at 12.44.35 AM.png

The Client ID and Client Secret have been generated for your application. Use the Copy feature to copy them into your application into the appropriate place(s). Remember to keep these values safe. Welcome will store these values here in Apps and Webhooks if you ever need to access them again, for any reason, you need to re-generate the Client ID and Secret, you’ll need to register a new application and follow these steps again.

FAQs: What is a successful connection/authorization**?**

A successful authorization is represented by an access_token. So whenever a client application successfully obtains an access_token for a CMP user, the authorization of that user for that client application is successful.

Why do I have to log in on the first access? Troubleshooting the Authentication Process.

You need to log in so that the authorization server can associate you as the impersonated user for the generated authorization tokens (access_token and refresh_token). Once the authorization tokens (access_token and refresh_token) are generated by the client application, the client application can periodically refresh the tokens without requiring re-authentication from the user. The very first time that you establish a successful connection with the Welcome Authorization Server, you will be prompted to enter a user ID and Password just as any other Welcome user. This is because the browser is serving as the front-end to the Welcome Authorization server. Simply enter an ID and Password on that first attempt, and then every subsequent attempt will look for your client application to verify the access token.

Questions? Contact [email protected]


Did this page help you?