Webhooks
Use the Webhooks destination to send Freshpaint data to any public HTTP endpoint. This integration can support a wide range of use cases that may not be supported by other destinations. For example you could use the Webhooks Destination to send data to Make (formerly known as Integromat) to perform no-code automation workflows.
- Connection Modes:
Client-side | Server-side | |
|---|---|---|
Web | ||
Mobile | ||
Server |
To set up the Webhooks destination, follow the following steps:
- 1.
- 2.Add the URL of the webhook that will receive your data
- 3.(Optional) Add any headers that need to be sent to your webhook. For example some webhooks may require the
Content-Type: application/jsonheader.
- 4.(Optional) Add additional webhook URLs if you want to send data to additional webhooks.
When you send an event to the Webhooks destination from Freshpaint, Freshpaint will send an HTTP POST request to each of the webhooks you've configured. The body of the request will look like the following:
{
"event": "a",
"type": "track",
"timestamp": "2022-12-28T21:16:50Z",
"messageId": "iI5pcrFfZHTuAfEu1DZ6Mg==",
"anonymousId": "1855a980cb1529-066ed15036156b-18525635-13c680-1855a980cb2178a",
"context": {
"page": {
"url": "https://example.com/",
"title": "Home Page",
"path": "/"
},
"library": {
"name": "freshpaint.js"
}
},
"properties": {
"customProp": 42
}
}
By default, identify events are not sent to the Webhooks destination. Enable them on the Webhooks destination configuration page under "Options".
When you call
freshpaint.identify('[email protected]', {"phone": "+15558675309"}), the body of the HTTP POST request sent to each webhook will look like this:{
"type": "identify",
"timestamp": "2022-12-28T22:00:25Z",
"messageId": "Zi1TKug6D8lLqNUD1v0i1w==",
"anonymousId": "1855a980cb1529-066ed15036156b-18525635-13c680-1855a980cb2178a",
"userId": "[email protected]",
"context": {
"page": {
"url": "https://example.com/",
"title": "Home Page",
"path": "/"
},
"library": {
"name": "freshpaint.js"
}
},
"properties": {},
"traits": {
"phone": "+15558675309"
}
}
By default, pageview events are not sent to the Webhooks destination. Enable them on the Webhooks destination configuration page under "Options".
When a pageview event occurs, the body of the HTTP POST request sent to each webhook will look like this:
{
"type": "page",
"timestamp": "2022-12-28T21:51:30Z",
"messageId": "icgQY4taV/WsZPiE9/0ZaA==",
"anonymousId": "1855a980cb1529-066ed15036156b-18525635-13c680-1855a980cb2178a",
"context": {
"page": null,
"library": {
"name": "freshpaint.js"
}
},
"properties": {
"url": "https://example.com/",
"title": "Example Domain",
"path": "/"
}
}
When you call
freshpaint.group("Acme, Inc", {"companyId": "1234"}), the body of the HTTP POST request sent to each webhook will look like this:{
"type": "group",
"timestamp": "2022-12-28T21:56:23Z",
"messageId": "7Kx9d7JNjo3Tbi9IcFITYw==",
"anonymousId": "1855a980cb1529-066ed15036156b-18525635-13c680-1855a980cb2178a",
"context": {
"page": {
"url": "https://example.com/",
"title": "Home Page",
"path": "/"
},
"library": {
"name": "freshpaint.js"
}
},
"groupId": "Acme, Inc",
"properties": {},
"traits": {
"companyId": "1234"
}
}
Here is what each piece of the HTTP POST request body means:
Key | Type | Description |
|---|---|---|
event | string | The name of the event |
type | string | The type of the event, for example "track", "identify", "page", or "group" |
timestamp | string | The time the event occurred.
Example: "2022-08-08T17:15:45Z" |
messageId | string | Unique id identifying this event |
anonymousId | string | The ID of the device the identify call was performed on |
userId | optional string | An identifier that uniquely identifies the user that performed the event (usually email address) |
groupId | optional string | For group events, a string that uniquely identifies the group this user belongs to (such as a company name). |
context.page | object | Data about the page that the event was performed on |
context.library | object | Data about the Freshpaint SDK that was used to capture this event |
properties | object | Any additional event properties for Track and Page events |
traits | object | Any additional properties of the user (for identify events) or group (for group events) |
Freshpaint allows you to configure custom integration settings for Webhooks. To do this, navigate to Destinations > Apps > Webhooks and click "Configure" for Options.
This will open a modal where you can check the options you would like to enable and click "Save". The following options are available:
- 1.Enable Identify Events - By default, identify events are not sent to webhooks. Enable this option to send identify events to your webhook(s) with information about who your users are.
- 2.Enable Pageview Events - By default, pageview events are not sent to webhooks. Enable this option to send pageview events automatically collected by Freshpaint to your webhook(s). Note that this does not affect pageview events defined on the Event Library page.
- Each webhook must be accessible from the public internet.
- When Freshpaint sends an event to a webhook, the service must respond within 5 seconds. After 5 seconds Freshpaint will record a timeout error.
- If you configure multiple webhooks, Freshpaint will send the same events to each webhook. They must each respond within 5 seconds, otherwise Freshpaint will record a timeout error. Also, if the total time taken for all webhooks exceeds 25 seconds, Freshpaint will record a timeout error.
- If you configure multiple webhooks, Freshpaint guarantees delivery to at least one webhook. This means that if Freshpaint successfully delivers an event to some of your webhooks but encounters an error with others, the delivery will not be retried. If Freshpaint encounters errors with all of the configured webhooks, the event will be retried later.
Last modified 1mo ago