Skip to content

docs: Add calendar-day deduplication trigger options for Destinations and Workflows #16486

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
inkeep wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs: Add calendar-day deduplication trigger options for Destinations and Workflows #16486

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5a91084
docs(cdp/destinations): add trigger options section with calendar-day…
inkeep[bot] Apr 21, 2026
96e57aa
docs(workflows): add trigger frequency section with calendar-day option
inkeep[bot] Apr 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 22 additions & 2 deletions contents/docs/cdp/destinations/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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.

Expand Down
47 changes: 31 additions & 16 deletions contents/docs/workflows/workflow-builder.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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)

Expand All @@ -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:
Expand Down
Loading