Integration Concepts
Shared concepts and reference material for Sesamy's built-in integrations.
How Integrations Work
When something changes in Sesamy, such as a new subscription, a user update, or a completed purchase, the platform fires an event. Built-in integrations listen for these events and automatically sync the relevant data to external services. Each integration handles the data differently depending on its purpose.
You configure an integration by providing credentials to Sesamy support. Once active, the integration runs server-side with no code changes needed on your end.
Building your own integration?
This page covers Sesamy's built-in integrations. If you want to receive raw events at your own HTTP endpoint, see Handling Webhooks.
Available Integrations
Email and CRM
These integrations sync subscriber profiles, subscription data, and tags to your email marketing or CRM platform. They respond to all eight event types.
- Mailchimp -- Syncs contacts with merge fields, tags, and activity tracking. Supports segmentation by subscription status and product access.
- HubSpot -- Creates and updates CRM contacts with subscription properties. Auto-creates dropdown options for active products.
- Rule -- Syncs subscribers with 50+ custom fields covering user profile, billing, products, and entitlements. Nordic marketing automation platform.
- Make.as -- Syncs subscriber data, product catalogues, and per-contract subscriptions. Supports syncing to multiple lists in parallel.
- Mailmojo -- Syncs contact data and tags. Preserves existing non-Sesamy tags and conditionally updates name and phone fields.
Conversion Tracking
These integrations send purchase events to advertising and analytics platforms. They respond only to checkout.1#confirm events.
- Google Analytics 4 -- Sends
purchaseevents via the GA4 Measurement Protocol with full ecommerce data including items, tax, and coupon codes. - Facebook / Meta -- Sends Purchase events to the Conversions API with hashed user data for ad attribution.
- Twitter / X -- Sends conversion events to the X Ads Conversions API with hashed user identifiers and product details.
- Kilkaya -- Sends server-side tracking pixel requests with purchase option details and UTM campaign parameters.
Automation
- Webhooks -- Forward raw event payloads to any HTTP endpoint, or build your own webhook consumer.
Sesamy Tags
Tags are string labels synced to subscriber records in email and CRM platforms. They provide a way to segment subscribers based on their Sesamy subscription state, active products, and custom metadata.
How tags work
- All Sesamy-managed tags start with the
sesamy_prefix - Only
sesamy_tags are modified by integrations. Tags you add manually or through other tools are never removed - Tags are truncated to 99 characters maximum
- Duplicate tags are removed after truncation
Tag patterns
| Pattern | Description | Example |
|---|---|---|
sesamy_active_subscriber | User has at least one active subscription | sesamy_active_subscriber |
sesamy_overdue_contract | User has at least one overdue contract | sesamy_overdue_contract |
sesamy_has_external_access | User has an externally granted entitlement | sesamy_has_external_access |
sesamy_has_gifted_subscription | Subscriber's access is paid for by someone else (a gifted subscription) | sesamy_has_gifted_subscription |
sesamy_active_entitlement_{title} | One tag per active entitlement (slugified product type and title) | sesamy_active_entitlement_publication-premium-magazine |
sesamy_active_sku_{sku} | One tag per active SKU | sesamy_active_sku_mag-001 |
sesamy_active_sku_po_{sku-po} | One tag per active SKU and purchase option ID | sesamy_active_sku_po_mag-001-po-123 |
sesamy_made_single_purchase | User has purchased at least one article | sesamy_made_single_purchase |
sesamy_tag_{custom} | One tag per custom tag on the user profile | sesamy_tag_vip |
Tags are used by: Mailchimp, Rule, Make.as, and Mailmojo.
HubSpot does not use tags
HubSpot uses contact properties instead. See the HubSpot integration page for details.
Event Payload
Every event delivered to an integration carries the same payload structure:
| Field | Type | Description |
|---|---|---|
eventType | string | The type of event that occurred |
vendorId | string | The vendor (publisher) identifier |
userId | string | The user identifier |
contractId | string | (Optional) Contract identifier, when applicable |
entitlementId | string | (Optional) Entitlement identifier, when applicable |
checkoutId | string | (Optional) Checkout identifier, when applicable |
occured_at | string | ISO 8601 timestamp of when the event occurred |
Event Types
Eight standard events are available. Not every integration handles all of them.
| Event | Description |
|---|---|
userVendor.1#new | A new user registered with a vendor |
userVendor.1#update | A user profile was updated |
contract.1#purchased | A subscription contract was purchased |
contract.1#update | A contract status changed (renewal, expiry, etc.) |
contract#cancelRequest | A user requested cancellation |
entitlement.1#new | A new entitlement was created for a user |
entitlement.1#update | An existing entitlement was updated |
checkout.1#confirm | A checkout was completed (purchase confirmed) |
Which integrations handle which events
| Category | Integrations | Events |
|---|---|---|
| Email and CRM | Mailchimp, HubSpot, Rule, Make.as, Mailmojo | All 8 events |
| Conversion Tracking | GA4, Facebook, Twitter/X, Kilkaya | checkout.1#confirm only |
| Automation | Webhooks | 6 events (all except entitlement events) |
Error Handling and Retries
All built-in integrations follow the same retry behaviour:
| Response | Behaviour |
|---|---|
| HTTP 2xx | Success. Event consumed. |
| HTTP 429 (Too Many Requests) | Retried with exponential backoff. |
| HTTP 4xx (except 429) | Permanent failure. Event consumed without retry. |
| HTTP 5xx | Retried with exponential backoff. |
| Network error | Retried with exponential backoff. |
Events that fail after all retries are logged for investigation.
Next Steps
- Handling Webhooks -- build your own webhook endpoint to receive raw events
- Mailchimp -- email marketing with merge fields and tags
- HubSpot -- CRM contact sync with subscription properties
- Google Analytics 4 -- server-side purchase tracking
- Webhooks -- forward events to any URL or build your own consumer