Customer.io integration

Customer.io is a marketing automation and customer engagement platform. This integration lets your WeWeb backend identify people, track events, manage devices, and send transactional emails and push notifications via Customer.io’s Track API and App API.

Use cases

• Identify users and set traits (attributes) from sign-up or profile updates
• Track behavioral events (e.g. purchase, signup, feature_used) for segmentation and campaigns
• Merge anonymous and identified profiles when a user signs in
• Register and remove devices for push notifications
• Suppress or unsuppress customers from messaging
• Send transactional emails and push notifications from backend workflows

Setup

1. In Customer.io, open Settings → API Credentials and note your Site ID, Track API Key (for identifying and tracking), and optionally App API Key (for transactional messages and broadcasts).
2. In WeWeb, go to the Settings tab → Integrations → Customer.io → Add connection.
3. For each environment (Editor, Staging, Production), set:
   • Site ID — From Customer.io API Credentials.
   • Write API Key — (If used in your setup; otherwise leave blank when only Track/App keys are required.)
   • Track API Key — Used for identifying customers and tracking events.
   • App API Key — Optional; required for Send Transactional Email and Send Push.
   • Region — US or EU to match your Customer.io data region.
4. Save and test with Identify Customer or Track Event using a test customer ID.

Common pitfalls (setup & usage)

Wrong API key for the action

Track actions (identify, track event, add device, etc.) use the Track API Key. Send Transactional Email and Send Push use the App API Key. If an action fails with an auth error, confirm you’re using the correct key and that it’s set for the right environment.

Region mismatch

Set Region to US or EU to match your Customer.io workspace. Using the wrong region can cause auth or routing failures.

Customer ID consistency

Use a stable identifier (e.g. your app’s user ID or email) for Customer Identifier across Identify and Track Event so Customer.io can attribute events to the same person.

All Actions

This integration provides Track API and App API actions.

Action	Description
Identify Customer	Create or update a person and set traits (Track API)
Track Event	Send a behavioral event for a person (Track API)
Track Anonymous	Track an event for an anonymous visitor (Track API)
Destroy Customer	Delete a person and their data (Track API)
Add Device	Register a device for push notifications (Track API)
Delete Device	Remove a device (Track API)
Suppress Customer	Suppress a person from messaging (Track API)
Unsuppress Customer	Remove suppression (Track API)
Merge Customers	Merge two profiles (Track API)
Send Transactional Email	Send a transactional email (App API)
Send Push	Send a push notification (App API)

Other actions (e.g. Identify, Track, Page, Screen, Group, Alias, Reset) may be available in the action picker for compatibility; the main backend actions above map to the Track and App APIs described here.

Action details

Identify Customer

Create or update a person in Customer.io and set attributes (traits). Use a stable Customer Identifier (e.g. user ID or email).

Display Key	Example Input	Description	Restrictions
Customer Identifier	"user_123" or "user@example.com"	Unique ID or email for the person	Required
Traits	{"first_name": "John", "plan": "premium"}	Attributes to set on the profile	Object

Track Event

Record a behavioral event for an identified person (e.g. purchased, signed_up).

Display Key	Example Input	Description	Restrictions
Customer Identifier	"user_123" or "user@example.com"	Person to attach the event to	Required
Event Properties	{"product_id": "123", "price": 29.99}	Optional data attached to the event	Object

Track Anonymous

Track an event for an anonymous visitor (anonymous_id). Use Merge Customers later to attach this activity to an identified person.

Display Key	Example Input	Description	Restrictions
Anonymous ID	"anon_abc123"	Anonymous visitor identifier	Required
Event Properties	{"page": "pricing"}	Optional data for the event	Object

Destroy Customer

Permanently delete a person and their data from Customer.io.

Display Key	Example Input	Description	Restrictions
Customer Identifier	"user_123" or "user@example.com"	Person to delete	Required

Add Device

Register a device (push token) for a person so they can receive push notifications.

Display Key	Example Input	Description	Restrictions
Customer Identifier	"user_123" or "user@example.com"	Person to attach the device to	Required
Device ID	"device_token_abc"	Push token / device identifier	Required
Platform	"ios" or "android"	Device platform	Required
Attributes	{"app_version": "1.0.0"}	Optional device attributes	Object

Delete Device

Remove a device (push token) from a person.

Display Key	Example Input	Description	Restrictions
Customer Identifier	"user_123" or "user@example.com"	Person who owns the device	Required
Device Token	"device_token_abc"	Token of the device to remove	Required

Suppress Customer

Suppress a person so they no longer receive messages.

Display Key	Example Input	Description	Restrictions
Customer Identifier	"user_123" or "user@example.com"	Person to suppress	Required

Unsuppress Customer

Remove suppression for a person.

Display Key	Example Input	Description	Restrictions
Customer Identifier	"user_123" or "user@example.com"	Person to unsuppress	Required

Merge Customers

Merge the secondary profile into the primary; the secondary is deleted. Use after a user signs in to merge anonymous activity into their identified profile.

Display Key	Example Input	Description	Restrictions
Primary Identifier Type	"id" or "email"	Type of the primary identifier	Required
Primary Identifier	"user_123"	Identifier of the profile to keep	Required
Secondary Identifier Type	"id" or "email"	Type of the secondary identifier	Required
Secondary Identifier	"anon_abc123"	Identifier of the profile to merge in and delete	Required

Send Transactional Email

Send a transactional email using a Customer.io transactional message template. Requires App API Key.

Display Key	Example Input	Description	Restrictions
Transactional Message ID	"1"	ID of the transactional message template	From Customer.io
To	"recipient@example.com"	Recipient email	Required
Identifiers	{"id": "user_123"} or {"email": "user@example.com"}	Associate message with a person	Optional
From, Subject, Body, etc.	—	Override template content; see action in WeWeb	Optional

Documentation: Customer.io API – Send transactional email

Send Push

Send a push notification via a Customer.io transactional message or with inline title/message. Requires App API Key.

Display Key	Example Input	Description	Restrictions
Transactional Message ID	"1"	ID of the transactional push template	Optional if title/message provided
To	Device identifier or person identifier	Target for the push	—
Identifiers	{"id": "user_123"}	Associate with a person	Optional
Title, Message, Link, Image URL, etc.	—	Override or supply content; see action in WeWeb	Optional

Documentation: Customer.io API – Send push

Error handling

Error code and type	Reason
401 Unauthorized	Invalid or missing Site ID or API key; wrong key type (Track vs App).
403 Forbidden	Key does not have permission for the operation.
404 Not Found	Person or resource not found.
422 Unprocessable Entity	Invalid payload (e.g. missing required field, bad format).
429 Too Many Requests	Rate limit; retry with backoff.

FAQs

Where do I find my Site ID and API keys?

In Customer.io go to Settings → API Credentials. Site ID and Track API Key are used for identify/track/device actions. App API Key is used for transactional email and push.

US vs EU region

Choose US or EU in the connection to match the region where your Customer.io workspace is hosted. Using the wrong region can cause authentication failures.