Links

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.

Destination Info

Client-side
Server-side
Web
Mobile
Server

Getting Started

To set up the Webhooks destination, follow the following steps:
  1. 1.
    Go to the Webhooks configuration page in Freshpaint and click "Configure"
  2. 2.
    Add the URL of the webhook that will receive your data
  3. 3.
    (Optional) Add any headers that need to be sent to your webhook. For example some webhooks may require the Content-Type: application/json header.
  4. 4.
    (Optional) Add additional webhook URLs if you want to send data to additional webhooks.

Events

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
}
}

Identify

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"
}
}

Page

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": "/"
}
}

Group

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"
}
}

Payload Format

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)

Configuration Options

Integration Settings / Options

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. 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. 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.

Considerations

  • 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