Linking Particle as a source

Particle forwards the events your devices publish, but it doesn't store them. Connect Particle to PostHog to keep a history of your IoT (internet of things) device data, with no server of your own. Every Particle.publish() that matches your event name prefixes arrives as a PostHog event on that device, so you can build insights, dashboards, and alerts on device data. PostHog also syncs your device list into the Data Warehouse.

Prerequisites

• A Particle account with devices that publish events with Particle.publish().
• Permission to add an API user to your Particle product, or to your sandbox if your devices aren't in a product.

Adding a data source

1. In PostHog, go to the Sources tab of the data pipeline section.
2. Click + New source and click Link next to this source.
3. Enter your credentials (see Configuration below) and click Next.
4. Select the tables you want to sync, choose a sync method and frequency, then click Import.

Once the syncs are complete, you can start querying this data in PostHog.

You need three values:

• Access token: the token depends on where your devices are.
  • Product devices: create an API user in the Particle console. Open your product, go to Team, and click Add API user. Give it these scopes:
    • devices:list to sync your device list
    • integrations:list, integrations:create, and integrations:remove so PostHog can manage its webhooks
  • Sandbox devices: Particle has no API users for the personal sandbox, so use a personal access token for your account. Create one with the Particle CLI: particle token create --never-expires. This token can read your devices and manage your webhooks.
• Product ID: the ID of your Particle product. Leave it empty to use the devices you own in your sandbox.
• Event name prefixes: a comma-separated list of the event names to send to PostHog. Particle matches event names by prefix and has no wildcard, so env/ receives env/temp and env/humidity.

When you select the events table, PostHog creates one Particle webhook per prefix. You can see them under Integrations in the Particle console, named PostHog (<prefix>).

How device events appear in PostHog

Each Particle event becomes a PostHog event:

PostHog doesn't create person profiles for devices. For example, a device that publishes {"temp": 21.5} as env/temp sends an env/temp event with a temp property of 21.5, which you can chart as an average per device.

Particle delivers webhooks at least once. A retried delivery can create a duplicate event. The events warehouse table removes duplicates by Particle's event ID.

Sync modes

Each table can be synced in one of several modes, depending on what the source supports:

• Webhook (when available) – the source pushes changes to PostHog in real time. Fastest freshness, lowest ongoing cost, and the only mode that reliably captures updates and deletes.
• Incremental – only new or updated rows are synced on each run, using a cursor field (such as an updated_at timestamp). Cheaper than a full refresh, but deletes aren't captured.
• Append only – new rows are appended using a cursor field; existing rows are never updated. Ideal for immutable, append-only tables like event logs.
• Full refresh – the whole table is reloaded on every sync. Use it when a table has no reliable cursor or when you need deletions reflected.

See sync methods for a full explanation of how each mode works and how to choose between them.

The devices table uses full refresh. The events table uses webhooks only, because Particle doesn't keep an event history to import. Events published before you connect the source are not imported.

Set up the webhook manually

If PostHog can't create the webhooks, for example because the token is missing an integration scope, create one webhook per prefix in the Particle console:

1. Go to Integrations > Add new integration > Webhook.
2. Set the event name to your prefix, the URL to the webhook URL PostHog shows, and the request type to POST.
3. Under Advanced settings, set a custom body of {{{PARTICLE_EVENT_JSON}}} and turn off the default data.
4. Add these query parameters: event = {{{PARTICLE_EVENT_NAME}}}, device_id = {{{PARTICLE_DEVICE_ID}}}, published_at = {{{PARTICLE_PUBLISHED_AT}}}, event_id = {{{PARTICLE_EVENT_ID}}}, product_id = {{{PRODUCT_ID}}}, and firmware_version = {{{PRODUCT_VERSION}}}.
5. Add the header Content-Type: application/json, and a header x-posthog-webhook-secret with a value of your choosing.
6. Paste the same secret into the Webhook secret field in PostHog.

Configuration

Supported tables

Troubleshooting

• No events arrive: check that your event names start with one of your prefixes. Prefixes are case sensitive. In the Particle console event log, a hook-sent event shows that Particle sent the webhook, and a hook-error event shows that it failed.
• The token can't manage integrations: for a product, add the integrations:list, integrations:create, and integrations:remove scopes to the API user, then reconnect. For sandbox devices, use a personal access token instead of a product API user token.
• Product not found: check the product ID, and check that the API user belongs to that product.

If your sync is failing or data looks wrong, see the Data warehouse troubleshooting guide. If that doesn't help, contact support – we're happy to help.