Configuring the Push API

Updated on 12 Aug 2025
6 Minutes to read

Print
Share
Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback

The Push API can be configured within CX Builder by any user with Client Admin or Client User with Integration permissions in the system. This feature is available in both the Staging and Production environments.

Adding a New Integration

Step #	Description	CX Builder
1	Once you are signed in, click on API Management in the left menu column. Click on the Push API Integration tab. This is the “home page” of the Push API Integration UI, where you will see a list of existing integrations for the selected client (if any exist). Note: If you do not see the API Management module on the left menu, please check that you have either Client Admin or Client User with Integration Permissions in the system.
2	To add an integration, click the “ADD INTEGRATION” button. A modal will pop up with a dropdown, where you can select the authentication type of the integration.
3	The types of supported authentication methods are as follows. Follow the links below to find instructions on how to configure each of the authentication methods. Basic Authentication: Username/Password Custom: API Key or No Authentication OAuth: Tokenized access Please note that the Salesforce Packages are covered under those specific sections of the documentation site.

Step #

Description

CX Builder

Once you are signed in, click on API Management in the left menu column. Click on the Push API Integration tab. This is the “home page” of the Push API Integration UI, where you will see a list of existing integrations for the selected client (if any exist).

Note: If you do not see the API Management module on the left menu, please check that you have either Client Admin or Client User with Integration Permissions in the system.

To add an integration, click the “ADD INTEGRATION” button. A modal will pop up with a dropdown, where you can select the authentication type of the integration.

The types of supported authentication methods are as follows. Follow the links below to find instructions on how to configure each of the authentication methods.

Basic Authentication: Username/Password

Custom: API Key or No Authentication

OAuth: Tokenized access

Please note that the Salesforce Packages are covered under those specific sections of the documentation site.

Basic Authentication

Step #	Description	CX Builder
1	Settings Name: This is the name of the integration you are creating, and can be named whatever you wish to refer to it as. URI/Endpoint: Uniform Resource Indicator. Similar to and should resemble a URL. This is the address at which this integration will be authenticated. Username: Enter or paste in the username provided by the client. Note that after you submit the integration, you will still be able to view the username in plaintext, but it is being encrypted on the backend. Password: Enter or paste in the password provided by the client. Like the username, this will also be encrypted in the backend, however, after saving you will be able to view only the last four characters of the decrypted password unmasked. (HTTP) Method: POST, PUT, GET. Most often the value should be POST.
2	Headers (Optional) This step is optional, and can be skipped if no custom headers were provided. If custom headers were provided, you may enter up to ten key-value pairs. If any of the values are sensitive, you may select the checkbox beneath the value. After saving, this value will be encrypted, however, upon subsequently viewing in the UI, you will be able to see the last four characters of the decrypted value. Sensitive headers cannot be edited or made non-sensitive after saving--if you wish to update them, you must delete the pair and create a new pair.
3	Events Events: These are push events, which are typically designated by the client. Here is documentation on available push events: Push Events. Selecting events is not required, but without selecting anything there will be no traffic to the endpoint that was provided. Activation or Saving: After you fill out all of the required fields, you have two options for saving. Activate: the integration will be added and immediately activated. Save & Exit: if you do not wish to have this integration activated immediately, you can select this option; the integration will not be active until you decide to activate it in the future.

Step #

Description

CX Builder

Settings

Name: This is the name of the integration you are creating, and can be named whatever you wish to refer to it as.

URI/Endpoint: Uniform Resource Indicator. Similar to and should resemble a URL. This is the address at which this integration will be authenticated.

Username: Enter or paste in the username provided by the client. Note that after you submit the integration, you will still be able to view the username in plaintext, but it is being encrypted on the backend.

Password: Enter or paste in the password provided by the client. Like the username, this will also be encrypted in the backend, however, after saving you will be able to view only the last four characters of the decrypted password unmasked.

(HTTP) Method: POST, PUT, GET. Most often the value should be POST.

Headers (Optional)

This step is optional, and can be skipped if no custom headers were provided. If custom headers were provided, you may enter up to ten key-value pairs. If any of the values are sensitive, you may select the checkbox beneath the value. After saving, this value will be encrypted, however, upon subsequently viewing in the UI, you will be able to see the last four characters of the decrypted value. Sensitive headers cannot be edited or made non-sensitive after saving--if you wish to update them, you must delete the pair and create a new pair.

Events

Events: These are push events, which are typically designated by the client. Here is documentation on available push events: Push Events. Selecting events is not required, but without selecting anything there will be no traffic to the endpoint that was provided.

Activation or Saving: After you fill out all of the required fields, you have two options for saving. Activate: the integration will be added and immediately activated. Save & Exit: if you do not wish to have this integration activated immediately, you can select this option; the integration will not be active until you decide to activate it in the future.

Custom Authentication

Step #	Description	CX Builder
1	Settings Name: This is the name of the integration you are creating, and can be named whatever you wish to refer to it as. URI/Endpoint: Uniform Resource Indicator. Similar to and should resemble a URL. This is the address at which this integration will be authenticated. (HTTP) Method: POST, PUT, GET. Most often the value should be POST.
2	Headers This is where “Header Name” (also referred to as “API Key Header”) and “Header Value” (also referred to as “API Key”) should be entered. You may also enter up to ten key-value pairs. If any of the values are sensitive, you may select the checkbox beneath the value. After saving, this value will be encrypted, however, upon subsequently viewing in the UI, you will be able to see the last four characters of the decrypted value. Sensitive headers cannot be edited or made non-sensitive after saving--if you wish to update them, you must delete the pair and create a new pair.
3	Events Events: These are push events, which are typically designated by the client. Here is documentation on available push events: Push Events. Selecting events is not required, but without selecting anything there will be no traffic to the endpoint that was provided. Activation or Saving: After you fill out all of the required fields, you have two options for saving. Activate: the integration will be added and immediately activated. Save & Exit: if you do not wish to have this integration activated immediately, you can select this option; the integration will not be active until you decide to activate it in the future.

Step #

Description

CX Builder

Settings

Name: This is the name of the integration you are creating, and can be named whatever you wish to refer to it as.

URI/Endpoint: Uniform Resource Indicator. Similar to and should resemble a URL. This is the address at which this integration will be authenticated.

(HTTP) Method: POST, PUT, GET. Most often the value should be POST.

Headers

This is where “Header Name” (also referred to as “API Key Header”) and “Header Value” (also referred to as “API Key”) should be entered. You may also enter up to ten key-value pairs. If any of the values are sensitive, you may select the checkbox beneath the value. After saving, this value will be encrypted, however, upon subsequently viewing in the UI, you will be able to see the last four characters of the decrypted value. Sensitive headers cannot be edited or made non-sensitive after saving--if you wish to update them, you must delete the pair and create a new pair.

Events

Events: These are push events, which are typically designated by the client. Here is documentation on available push events: Push Events. Selecting events is not required, but without selecting anything there will be no traffic to the endpoint that was provided.

Activation or Saving: After you fill out all of the required fields, you have two options for saving. Activate: the integration will be added and immediately activated. Save & Exit: if you do not wish to have this integration activated immediately, you can select this option; the integration will not be active until you decide to activate it in the future.

OAuth

Step #	Description	CX Builder
1	Settings Name: This is the name of the integration you are creating, and can be named whatever you wish to refer to it as. URI/Endpoint: Uniform Resource Indicator. Similar to and should resemble a URL. This is the address at which this integration will be authenticated. Grant Type: Currently, the only option for this field is client_credentials, so please select this value. If you require a Push API setup with a Grant Type that is not client_credentials, please contact your Relay Account team to discuss options. Client ID: This is the client ID provided by the Relay client. It possible that it is different than the Relay client ID. Client Secret: This can be thought of as a password, provided by the client, associated with the client-provided client ID above. Authentication URL: This is the address at which this integration will be authenticated. Many times it will look something like “https://company domain.com/words/token” where the word “token” is in the endpoint. Token (Optional): Optional, but required if provided by the client. If provided, this is a long value composed of different types of characters and can be thought of as a password for authentication. If the client did not provide a token value, it is likely that this field is not required, and should therefore be left blank. Scope (Optional): Optional, but required if provided by the client. The format of this can vary. Here are some examples of what the value for this field may look like: `urn:cable:scope:timeline-ingest` `https://app-messaging-que-dev.servicebus.windows.net/.default` `https://eapiqa.ibx.com/api/v1.0/ext/Relay` Resource (Optional): Optional, but required if provided by the client. The resource server handles authenticated requests after the application has obtained an access token. If the client did not provide a resource value, it is likely that this field is not required, and should therefore be left blank. HTTP Method: POST, PUT, GET. Most of the time it will be POST.
2	Headers This is where “Header Name” (also referred to as “API Key Header”) and “Header Value” (also referred to as “API Key”) should be entered. You may also enter up to ten key-value pairs. If any of the values are sensitive, you may select the checkbox beneath the value. After saving, this value will be encrypted, however, upon subsequently viewing in the UI, you will be able to see the last four characters of the decrypted value. Sensitive headers cannot be edited or made non-sensitive after saving--if you wish to update them, you must delete the pair and create a new pair.
3	Events Events: These are push events, which are typically designated by the client. Here is documentation on available push events: Push Events. Selecting events is not required, but without selecting anything there will be no traffic to the endpoint that was provided. Activation or Saving: After you fill out all of the required fields, you have two options for saving. Activate: the integration will be added and immediately activated. Save & Exit: if you do not wish to have this integration activated immediately, you can select this option; the integration will not be active until you decide to activate it in the future.

Step #

Description

CX Builder

Settings

Name: This is the name of the integration you are creating, and can be named whatever you wish to refer to it as.

URI/Endpoint: Uniform Resource Indicator. Similar to and should resemble a URL. This is the address at which this integration will be authenticated.

Grant Type: Currently, the only option for this field is client_credentials, so please select this value. If you require a Push API setup with a Grant Type that is not client_credentials, please contact your Relay Account team to discuss options.

Client ID: This is the client ID provided by the Relay client. It possible that it is different than the Relay client ID.

Client Secret: This can be thought of as a password, provided by the client, associated with the client-provided client ID above.

Authentication URL: This is the address at which this integration will be authenticated. Many times it will look something like “https://company domain.com/words/token” where the word “token” is in the endpoint.

Token (Optional): Optional, but required if provided by the client. If provided, this is a long value composed of different types of characters and can be thought of as a password for authentication. If the client did not provide a token value, it is likely that this field is not required, and should therefore be left blank.

Scope (Optional): Optional, but required if provided by the client. The format of this can vary. Here are some examples of what the value for this field may look like:

urn:cable:scope:timeline-ingest
https://app-messaging-que-dev.servicebus.windows.net/.default
https://eapiqa.ibx.com/api/v1.0/ext/Relay

Resource (Optional): Optional, but required if provided by the client. The resource server handles authenticated requests after the application has obtained an access token. If the client did not provide a resource value, it is likely that this field is not required, and should therefore be left blank.

HTTP Method: POST, PUT, GET. Most of the time it will be POST.

Headers

Events

Events: These are push events, which are typically designated by the client. Here is documentation on available push events: Push Events. Selecting events is not required, but without selecting anything there will be no traffic to the endpoint that was provided.

Activation or Saving: After you fill out all of the required fields, you have two options for saving. Activate: the integration will be added and immediately activated. Save & Exit: if you do not wish to have this integration activated immediately, you can select this option; the integration will not be active until you decide to activate it in the future.

Was this article helpful?

What's Next

Vanity URL

Table of contents

Adding a New Integration
Basic Authentication
Custom Authentication
OAuth