diff --git a/contents/docs/cdp/destinations/index.md b/contents/docs/cdp/destinations/index.md index 05369c99dff2..183f4cb4f511 100644 --- a/contents/docs/cdp/destinations/index.md +++ b/contents/docs/cdp/destinations/index.md @@ -3,7 +3,7 @@ title: Realtime analytics data exports showTitle: true --- -As PostHog data arrives, you can export it *immediately* to other tools. You can use this for things like: +As PostHog data arrives, you can export it _immediately_ to other tools. You can use this for things like: - Conversion tracking - Monitoring key events with your chat platform @@ -24,6 +24,25 @@ Instead of the firehose of all your PostHog data, you can construct a query that ![Filtering destinations](https://res.cloudinary.com/dmukukwp6/image/upload/filter_ui_8c7b1fb3be.png) +## Trigger options + +Control when a destination fires using trigger options. These settings deduplicate events to prevent duplicate deliveries. + +| Option | Description | +| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | +| **Run every time** | The destination fires for every matching event with no deduplication. | +| **Run once per interval** | Fires at most once within the specified time interval regardless of person or event. | +| **Run once per person per interval** | Fires at most once per person within the specified time interval (e.g., 24 hours). Uses a rolling time window. | +| **Run once per person per event name per interval** | Fires at most once per person per event name within the specified time interval. Uses a rolling time window. | +| **Once per person per day (UTC)** | Fires at most once per person per calendar day. The day boundary resets at midnight UTC. | +| **Once per person per event per day (UTC)** | Fires at most once per person per event name per calendar day. The day boundary resets at midnight UTC. | + +For interval-based options, you can configure both the time window (from 5 minutes to 24 hours) and an optional event threshold. + +The calendar-day options are useful when you don't want a rolling time window to suppress events across day boundaries. For example, with a rolling 24-hour interval, an event at 3pm Monday would block an event at 10am Tuesday. With the calendar-day option, events reset at midnight UTC each day. + +> **Note:** Calendar-day options use the UTC timezone, which may differ from your local timezone. + ## Testing The hardest part of integrating two services is making sure everything works as you expect. Every destination includes a built-in testing interface, enabling you to send real data from PostHog on-demand to your target service and debug any errors. @@ -50,13 +69,14 @@ The `person` object contains the latest information for the [person profile](/do ### How many events can I send to a destination? -There is no limit on the number of events to be processed but the system requires that the destination responds with healthy status codes (non 5xx) and in a timely fashion. +There is no limit on the number of events to be processed but the system requires that the destination responds with healthy status codes (non 5xx) and in a timely fashion. ### What can cause a destination to be automatically disabled? If the destination performs poorly (too many errors, too slow) for a prolonged period, your destination will be quarantined and eventually disabled. We will try to re-enable it automatically after a temporary disabled period before stopping it entirely. You then need to modify either the filters or the destination and re-enable it in the UI to try again. The key metrics that we observe to determine poor performance are: + 1. Errors thrown within the code (for example if you try to access a property that doesn't exist). 2. Repeatedly slow responses from the destination. Some slow HTTP calls are fine but if you send thousands of events and the destination can't keep up, we will eventually disable it to protect ourselves and the destination. diff --git a/contents/docs/workflows/workflow-builder.mdx b/contents/docs/workflows/workflow-builder.mdx index adaaf2c67a7e..8374718ebb13 100644 --- a/contents/docs/workflows/workflow-builder.mdx +++ b/contents/docs/workflows/workflow-builder.mdx @@ -2,7 +2,7 @@ title: Workflow builder --- -import CalloutBox from 'components/Docs/CalloutBox' +import CalloutBox from "components/Docs/CalloutBox"; Workflows are a collection of steps that automate a process or deliver messages to your users based on your configured logic. In PostHog, you can create a workflow using our no-code workflow builder. @@ -15,14 +15,14 @@ Workflows are a collection of steps that automate a process or deliver messages Workflows are composed of the following components: -| Component | Description | -| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Triggers](#triggers) | What starts the workflow. You can trigger a workflow from an event, a recurring schedule, a batch audience, a webhook, or a tracking pixel. | -| [Dispatches](#dispatches) | The messages you send, mail, slack, SMS, webhook, or any PostHog real time destinations. | -| [Delays](#delays) | Wait steps such as "wait 2 days" or "wait until condition is true." | -| [Audience splits](#audience-splits) | Target and split your users so you can automate some action for them or send a message with more specificity. | -| [PostHog actions](#posthog-actions) | Change a person's properties, or trigger other events, once a person reaches a specific point in your workflow. | -| [Output variables](#output-variables) | Store data from step results in workflow variables for use in later steps. | +| Component | Description | +| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| [Triggers](#triggers) | What starts the workflow. You can trigger a workflow from an event, a recurring schedule, a batch audience, a webhook, or a tracking pixel. | +| [Dispatches](#dispatches) | The messages you send, mail, slack, SMS, webhook, or any PostHog real time destinations. | +| [Delays](#delays) | Wait steps such as "wait 2 days" or "wait until condition is true." | +| [Audience splits](#audience-splits) | Target and split your users so you can automate some action for them or send a message with more specificity. | +| [PostHog actions](#posthog-actions) | Change a person's properties, or trigger other events, once a person reaches a specific point in your workflow. | +| [Output variables](#output-variables) | Store data from step results in workflow variables for use in later steps. | ## Draft and enabled workflows @@ -43,13 +43,13 @@ Draft workflows can also be archived, even if they contain invalid configuration Every workflow starts with a trigger. Triggers define what kicks off the workflow. -| Trigger type | Description | -| ------------------------ | ---------------------------------------------------------------------------------- | -| Event trigger | A captured [PostHog event](/docs/data/events) (e.g. `signed up`) | -| Webhook trigger | Programmatically start a workflow with an HTTP request | -| Schedule trigger | Run a workflow on a recurring schedule (e.g. daily, weekly, monthly) | -| Batch trigger | Run the workflow for each person matching an audience, on a recurring schedule | -| Tracking pixel trigger | Start the workflow when a 1x1 tracking pixel is loaded (e.g. in an email) | +| Trigger type | Description | +| ---------------------- | ------------------------------------------------------------------------------ | +| Event trigger | A captured [PostHog event](/docs/data/events) (e.g. `signed up`) | +| Webhook trigger | Programmatically start a workflow with an HTTP request | +| Schedule trigger | Run a workflow on a recurring schedule (e.g. daily, weekly, monthly) | +| Batch trigger | Run the workflow for each person matching an audience, on a recurring schedule | +| Tracking pixel trigger | Start the workflow when a 1x1 tracking pixel is loaded (e.g. in an email) | ### Event triggers @@ -110,6 +110,7 @@ You define the audience using person properties, cohorts, or feature flag filter The trigger shows an estimate of how many persons will be affected before you enable the workflow. A batch trigger combines two things: + - **Audience filters** — who should enter the workflow (e.g. person properties, cohorts, feature flags) - **A recurring schedule** — when the batch should run (same schedule picker as schedule triggers) @@ -121,6 +122,20 @@ When the pixel is loaded (e.g. when a recipient opens an email), the workflow fi You can pass data via query parameters on the pixel URL and map them to event properties in the trigger configuration. +### Trigger frequency + +For event-based triggers, you can control how often a workflow fires per person using the frequency setting. + +| Option | Description | +| ------------------------- | -------------------------------------------------------------------------------------------------------- | +| **Every time** | The workflow fires for every matching event. | +| **One time** | The workflow fires at most once per person. Once a person has entered the workflow, they can't re-enter. | +| **Once per calendar day** | The workflow fires at most once per person per calendar day. The day boundary resets at midnight UTC. | + +For the **One time** option, you can also configure a time interval to control how long the deduplication window lasts. + +> **Note:** The calendar-day option uses the UTC timezone, which may differ from your local timezone. + ## Dispatches Dispatches are the messages you send, mail, slack, SMS, webhook, or any PostHog real time destinations. There are 4 main types of dispatches: