Integration reference
Klaviyo Trigger and Action reference
Start Workflows from new profiles and events, manage customer profiles and lists, and send behavioral events to Klaviyo.
Authentication
Connect each customer's Klaviyo account through OAuth. FastHook uses PKCE, encrypts renewable credentials, and requests only the scopes required by the selected Trigger or Action.
- Trigger account type:
oauth2; reconnect byoauth. - Action connection type:
oauth2; available modes: Connected Klaviyo account.
Create or reuse the account from a Trigger or Action dialog, or manage it under Settings → Connected accounts. See Authentication and permissions for scopes and access diagnostics, or Connected accounts for reuse, reconnect, revocation, and credential rotation.
Scopes and permissions
Base Trigger authorization requests: accounts:read.
View 8 OAuth scopes used by current Actions
accounts:read, profiles:read, profiles:write, lists:read, lists:write, events:write, events:read, metrics:read
View 8 provider permissions or credential requirements
accounts:read, profiles:read, profiles:write, lists:read, lists:write, events:write, events:read, metrics:read
Operation-specific requirements appear in the tables below. Custom event selections can add scopes dynamically, so the current Trigger or Action dialog remains authoritative for the exact consent request.
Use Klaviyo as a Trigger
The current provider manifest contains 2 available Trigger definitions. Representative definitions include:
- New Profile
- New Event
View all 2 available Trigger definitions
| Trigger | Manifest key | Delivery | Additional scopes |
|---|---|---|---|
| New Profile | klaviyo.new_profile.polling | polling | profiles:read |
| New Event | klaviyo.new_event.polling | polling | events:read, metrics:read, profiles:read |
Choose the narrowest event definition that fits the Workflow. Configure provider-specific resource and event filters in the Source dialog before adding broader Workflow Filters.
Use Klaviyo Actions
The current Action manifest contains 11 operations. Representative Actions include:
- Create Profile
- Update Profile
- Add Profile to List
- Create Event
View all 11 available Action definitions
| Action | Manifest key | Access and auth | Manifest rate limit |
|---|---|---|---|
| Get Account | klaviyo.get_account | accounts:readFastHook-managed account | 1/second |
| List Profiles | klaviyo.list_profiles | profiles:readFastHook-managed account | 1/second |
| Get Profile | klaviyo.get_profile | profiles:readFastHook-managed account | 1/second |
| Create Profile | klaviyo.create_profile | profiles:writeFastHook-managed account | 1/second |
| Update Profile | klaviyo.update_profile | profiles:writeFastHook-managed account | 1/second |
| List Lists | klaviyo.list_lists | lists:readFastHook-managed account | 1/second |
| Get List | klaviyo.get_list | lists:readFastHook-managed account | 1/second |
| Add Profile to List | klaviyo.add_profile_to_list | lists:writeFastHook-managed account | 1/second |
| Remove Profile from List | klaviyo.remove_profile_from_list | lists:writeFastHook-managed account | 1/second |
| Create Event | klaviyo.create_event | events:writeFastHook-managed account | 1/second |
| Custom API Request | klaviyo.custom_api_request | accounts:read, events:read, events:write, lists:read, lists:write, metrics:read, profiles:read, profiles:writeFastHook-managed account | 1/second |
The Action editor reads its required permissions, fields, remote resource pickers, output schema, and rate limit from the provider manifest. Available fields can change with the selected operation and authentication mode.
Build a Workflow
- Create a Source using a Klaviyo Trigger definition.
- Create a Workflow with that Source as its Trigger.
- Add the required Klaviyo Action and select the connected account.
- Map Trigger or earlier-Step data into the Action fields with the field picker.
- Add a Filter, Paths, Delay, or Transformation when the route needs it.
- Activate the Workflow, produce a controlled event, and verify the run in Audit and in Klaviyo.
Troubleshooting Klaviyo
- The account is missing or cannot be selected
- Confirm the active FastHook team, provider, account status, and authentication mode. A disabled or revoked account cannot execute an Action.
- A resource picker is empty
- Verify that the connected provider identity can access the resource itself. OAuth consent does not add workspace, repository, channel, drive, project, base, or record permissions.
- The editor asks for additional scopes
- Reconnect the same account from the affected Trigger or Action so FastHook can request its current manifest scopes. Then reopen the editor and select the resource again.
- An active Workflow returns 401, 403, or a permission error
- Compare the selected operation’s access requirements below with the account recorded in Audit. Check provider-side membership and object access before repeating the Action.
- The provider returns 429 or a temporary 5xx
- Inspect the Step attempt and retryability in Audit. FastHook can retry temporary failures, but provider quotas and idempotency rules still apply.
Provider-specific checks
- New Profile and New Event poll every five minutes and keep a timestamp plus IDs at that timestamp, so equal-time records are not lost or emitted twice.
- New Event can watch every metric or one selected metric. Related metric and profile resources are included with the event when Klaviyo returns them.
- Klaviyo System Webhooks are limited to eligible Advanced KDP customers and app partners, so FastHook uses the public Events and Profiles APIs for broad customer compatibility.
- Create Event accepts an email profile identifier and optional properties, unique ID, value, and historical RFC 3339 time.
- Custom API Request stays on https://a.klaviyo.com/api/ and cannot override the host or authorization header.