In Connectif, it is possible to receive data from external systems to make use of information that is not registered by default on the platform. Through a custom integration, you can synchronize your contacts' data based on events generated in other platforms.
This article explains the types of custom integrations for receiving data and how to create such an event, with an example integration with an ERP.
1. Properties
Data Reception Events
Data reception events are a powerful tool to expand and customize Connectif according to your own use cases.
-
When creating a new reception event, you must specify the context:
Public API.
Webhook.
Web or Mobile App.
Reception Event via Public API
Reception events via Public API are the most secure mechanism, as they require an API Key. They are designed for events to be sent from your server to Connectif.
Features and limits:
The maximum event size is 512KB.
It is mandatory to define a required email field and primary key to identify the contact.
- It is possible to specify via the query string createContact whether to create or return an error when the contact associated with the event does not exist.
The workflow trigger node generated by a reception event via Public API will not have web context.
- They require strict validation and do not allow sending fields that are not defined in the event.
Important: these events cannot be sent from the browser. If you use web events, you can send them via Connectif JavaScript.
Reception Event via Webhooks
Reception events via Webhook are a more flexible mechanism, ideal when you do not control the data sender, for example, using a webhook from an external tool where you cannot change the emitted data format or cannot establish a security header with an API key.
Features and limits:
The maximum event size is 512KB.
It is mandatory to define a required email field and primary key to identify the contact.
- They always create the contact in Connectif if it does not exist.
- They allow defining JSON Pointer to map fields to complex structures. Ideal when the event information is in complex and nested objects.
- They do not return validation errors for unknown fields. This allows mapping only the fields of interest, ignoring others that will simply be discarded.
The workflow trigger node generated by a reception event via Webhook will not have web context.
Important: these events cannot be sent from the browser. If you use web events, you can send them via Connectif JavaScript.
Reception Event via Web or Mobile App
Reception events via Web or Mobile App allow sending events directly from the client side of your website or from your mobile app. For this, it is necessary to use the Web SDK or Mobile SDK respectively.
Features and limits:
Events via Web or App do not require a mandatory email field and primary key. Therefore, they can be sent for anonymous or known contacts during web or mobile app tracking.
The workflow trigger node generated by a reception event via Web or Mobile App will have web context. After this node, it is possible to use the Show web content node.
2. How the Creation of a Data Reception Event Works in Connectif
The process of creating a data reception event consists of several steps to follow, regardless of the chosen mechanism.
As an example, below is how to create a data reception event to connect an ERP with Connectif:
2.1. Creating the Custom Integration
1. Go to "Integrations > Custom" and click on Create new integration.
In our example, we will synchronize ERP data with Connectif.
2. Set the "Name" field to identify the integration.
3. (Optional) Customize the color, include a description, or categorize the integration.
4. Click on Update.
2.2 Creating and Configuring the "Receive Data" Event
(In this section, the reception event will be created and the fields where the received data will be stored will be configured).
5. In the Receive Data tab, click on Create new reception event.
6. In the pop-up window, choose the connection type for the event and click Go to editor. In our example, via Public API.
7. Assign a Name and an Alias to the event.
8. Click on Add a new field to create a field of type Email, to capture the contact's email address.
It is important that the email field is of type email and marked as Required and Is primary key, as it will be used to identify the contact.
9. Repeat the previous step as many times as the number of data fields you want to receive.
To learn more about custom fields, click here.
10. Click on Save and, on the confirmation screen, click on Back to event list.
2.3. Creating the API Key to Enable Data Reception
(This section explains how to generate the address to notify the created event type, the endpoint).
10. Go to "Store Settings > API and IP Access" and, under API Keys, click on Create new API key.
11. In the Custom Events section, enable the permission to Write.
12. Save the API key and, in the API Keys menu, locate the one you just created and click the button to copy it (indicated in the image).
13. Use the API key to make the event submission request from your system.
Creating and using the API key is only necessary for reception events via API. For more information, consult the Connectif API documentation.
2.4. Obtaining the Notification Endpoint
(This section explains how to generate the address to notify the created event type, the endpoint).
The endpoint works similarly to the webhook concept: it is a system that waits for an event to occur and reacts by transferring data to another application or system, in this case to Connectif, using an HTTP call.
14. In the Receive Data tab, click on Edit.
15. Click on Copy URL to copy the endpoint address to the clipboard.
2.5. Sending Data to Connectif
(This section explains how to establish communication with the endpoint and send data).
16. In your code, paste this URL along with the API Key and the request body to generate the reception event. For Webhook or Web/App events, you will not need to use the API Key.
If you need more information, review the Connectif API documentation.
17. Make the call to the endpoint to notify it of the event data.
Learn how to notify custom events via JavaScript in this article.
The call must be a POST request to the selected endpoint with JSON format. In the body of the call, it is necessary to specify the IDs of the fields configured in the event.
2.5.1 Example of Sending Data Using Postman (Webhook)
Once the reception event is configured in Connectif, you can perform data sending tests using Postman to verify that the information is received correctly.
Configure the request
- Open Postman and create a new request.
- Select the POST method.
- Enter the endpoint URL generated for the reception event.
Example:
https://webhook-api.connectif.cloud/{store-id}/custom-events/alias/webhook-event-example
Configure the headers
Add the necessary headers for sending data:
| Key | Value |
| Content-Type | application/json |
Configure the request body
Select Body > raw > JSON and enter a payload matching the fields defined in the event.
Example:
{
"email": "john.doe@example.org",
"phone": "+34666777888",
"name": "Hi there!"
}The attribute names must match the identifiers configured in the reception event.
Send the request
Click Send to make the request.
If the request is processed correctly, the event will be received by Connectif and can be used in workflows, segmentations, or automation processes.
It is recommended to verify the event reception through a test workflow or by reviewing the activity of the contact associated with the sent data.
Result:
The following image shows an example of a successfully made request from Postman and the response returned by Connectif.
2.5.2 Example of Sending Data Using Postman (API)
Once the reception event is configured and the API Key is created, you can use Postman to verify that Connectif correctly receives the sent data.
Configure the request
- Open Postman and create a new request.
- Select the HTTP method indicated in the endpoint documentation you are going to use.
- Enter the URL corresponding to the API endpoint.
Example:
https://api.connectif.cloud/custom-events/alias/api-event-example?createContact=true
Configure the headers
Add the credentials required by the endpoint via the corresponding headers.
| Key | Value |
| Content-Type | application/json |
| Authorization | ApiKey {api_key} |
Replace {api_key} with the corresponding Secret Key.
Configure the request body
Select Body > raw > JSON and enter a payload matching the fields defined in the event.
Example:
{
"email": "john.doe@example.org",
"name": "Hi there!",
"phone": "+34666777888"
}The attribute names must match the identifiers configured in the reception event.
Send the request
Click Send to make the request.
If the request is processed correctly, the API will return a successful response and the data will be registered in Connectif according to the functionality used.
Result:
The following image shows an example of a successful request made via Public API using an API Key with write permissions for custom events.
2.6. Synchronizing Data with Contact Information
(This section explains how to synchronize data in Connectif through a workflow).
18. Go to “Workflows”, click on Create new workflow and select Create blank workflow.
19. Create your workflow structure with the trigger node of type “Trigger [your integration name]” and the action node “Set field.”
20. In the node “Trigger Receive data from…,” click on (Edit node configuration).
21. Check that the data collected by the "Trigger Receive data from..." node, coming from the event in the external system, is correct.
If the data is not correct, you can edit it from the reception event configuration (STEP 2).
22. Click on Save.
23. In the “Set field” node, click on (Edit node configuration).
24. Map the variables to assign the information collected by the custom integration to the corresponding contact fields.
To learn more about assigning variables in the "Set field" node, click here.
25. Click on Update.
26. In the workflow, click Save to save changes and Start to activate it.
2.7. Creating a Dynamic Plus Segment of the Integration
With Connectif, you can create a Dynamic Plus Segment to filter by activities and fields related to the custom integration.
If you want to learn how to create a Dynamic Plus Segment with your integration's contacts, check this article.
Once you create a contact segment of the custom integration, it cannot be deleted. Also, if any of its fields are used as segmentation conditions, they cannot be deleted or edited either.
Success!
Your custom integration is ready to receive data.
Keep learning!
To take full advantage of your Connectif account, we recommend continuing with the following articles:
Custom integration to send data, to send data from Connectif to external systems or applications.
Detect and react to web links created outside Connectif, to identify and respond to clicks on any link on your website.
Integration with Facebook and Instagram, to manage your Facebook Ads account audiences with Connectif.
Integrated forms, to detect and capture existing forms on your website into Connectif.