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

• Supports Page, Track, and Identify, and Group calls

• Supports HIPAA mode

• Connection Modes:

	Client-side	Server-side
Web
Mobile
Server

Getting Started

To set up the Webhooks destination, follow the following steps:

1. Go to the Webhooks configuration page in Freshpaint and click "Configure"

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/json header.

   
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('[e-mail]', {"phone": "[phone]"}), 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": "[e-mail]",
    "context": {
        "page": {
            "url": "https://example.com/",
            "title": "Home Page",
            "path": "/"
        },
        "library": {
            "name": "freshpaint.js"
        }
    },
    "properties": {},
    "traits": {
        "phone": "[phone]"
    }
}

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

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.