Campaigns
Receive notifications when campaigns are triggered or completed.
Overview
Campaign webhooks notify your application when marketing campaigns interact with subscriptions. Use these events to trigger external workflows, sync campaign data with your marketing tools, or track campaign performance.
Use Cases
- Send personalized emails when a campaign targets a subscription
- Sync campaign run results with your CRM or analytics platform
- Trigger external marketing automations based on campaign events
- Track campaign performance metrics across systems
- Download export files when campaign runs complete
Events
| Event | Description |
|---|---|
campaign.triggered | A campaign was triggered for a specific subscription |
campaign.run_completed | A campaign run finished processing all subscriptions |
campaign.triggered
Triggered When
- A promotional campaign targets a subscription for renewal notification
- A renewal campaign processes a subscription approaching expiration
- A cancellation campaign processes a subscription being canceled
- A creation campaign processes a newly created subscription
Payload
The payload includes both subscription and campaign details, along with a magic link token for passwordless authentication.
{
"type": "campaign.triggered",
"id": "evt_a1b2C3d4E5f6g7H8i9J0k1L2",
"created": 1704067200,
"data": {
"campaign": {
"id": 123,
"name": "January Renewal Campaign",
"key": "JAN-2024-RENEW",
"description": "Renewal reminders for January expirations",
"site": {
"id": 1,
"name": "Main Site"
},
"plan": {
"id": 456,
"nickname": "Premium Annual",
"name_internal": "premium_annual",
"amount": 9999
},
"product": {
"id": 789,
"name": "Premium Membership",
"name_internal": "premium_membership"
},
"coupon": {
"id": 101,
"name": "Loyalty Discount",
"code": "LOYAL20",
"percent_off": 20
}
},
"magic_link_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"subscription": {
"id": 55555,
"expire_date": "2024-01-31T23:59:59.000000Z",
"days_to_expire": 15.5,
"recommended_plan_id": 457,
"address": {
"line1": "123 Main Street",
"line2": "Suite 100",
"city": "New York",
"state": "NY",
"country": "US",
"postal_code": "10001"
},
"plan": {
"id": 456,
"nickname": "Premium Annual",
"name_internal": "premium_annual",
"interval": "year",
"interval_count": 1,
"currency": "usd",
"amount": 9999
},
"product": {
"id": 789,
"name": "Premium Membership",
"name_internal": "premium_membership"
},
"user": {
"id": 67890,
"title": "Marketing Manager",
"company": "Acme Inc",
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]"
}
}
}
}campaign.run_completed
Triggered When
- A scheduled campaign run finishes processing all targeted subscriptions
- An on-demand campaign execution completes
- A campaign export file has been generated
Payload
{
"type": "campaign.run_completed",
"id": "evt_b2C3d4E5f6g7H8i9J0k1L2m3",
"created": 1704153600,
"data": {
"campaign": {
"id": 123,
"name": "January Renewal Campaign",
"type": "Renewal",
"description": "Renewal reminders for January expirations",
"action": "Both",
"run": {
"id": 999,
"key": "JAN-2024-RENEW-010124",
"date": 1704153600,
"download_link": "https://api.pelcro.com/core/campaigns/123/runs/999/report/download"
}
}
}
}Payload Fields
Campaign Object (campaign.triggered)
| Field | Type | Description |
|---|---|---|
id | integer | Unique identifier for the campaign |
name | string | Campaign display name |
key | string | Campaign key/code for tracking |
description | string | Campaign description |
site | object | Site the campaign belongs to (see Site Object) |
plan | object | Plan offered by the campaign, if any (see Plan Object) |
product | object | Product associated with the campaign plan |
coupon | object | Coupon offered by the campaign, if any (see Coupon Object) |
Campaign Object (campaign.run_completed)
| Field | Type | Description |
|---|---|---|
id | integer | Unique identifier for the campaign |
name | string | Campaign display name |
type | string | Campaign type: Promotional, Renewal, Cancellation, or Creation |
description | string | Campaign description |
action | string | Campaign action: Notification, Export, Both, Renewal, Cancellation, Cancellation And Export, Creation, or Creation And Export |
run | object | Details about the completed run (see Run Object) |
Subscription Object (Nested in campaign.triggered)
| Field | Type | Description |
|---|---|---|
id | integer | Unique identifier for the subscription |
expire_date | string | ISO 8601 timestamp when the subscription expires |
days_to_expire | float | Number of days until expiration (can be negative if expired) |
recommended_plan_id | integer | ID of the recommended renewal plan, if configured |
address | object | Subscription shipping address (see Address Object) |
plan | object | Current subscription plan (see Plan Object) |
product | object | Product associated with the subscription plan |
user | object | Subscriber details (see User Object) |
Run Object (Nested in campaign.run_completed)
| Field | Type | Description |
|---|---|---|
id | integer | Unique identifier for the campaign run |
key | string | Run key/code for tracking |
date | integer | Unix timestamp when the run was created |
download_link | string | URL to download the export file (null if no export) |
Site Object (Nested)
| Field | Type | Description |
|---|---|---|
id | integer | Site ID |
name | string | Site display name |
Plan Object (Nested)
| Field | Type | Description |
|---|---|---|
id | integer | Plan ID |
nickname | string | Plan display name |
name_internal | string | Internal plan identifier |
interval | string | Billing interval: day, week, month, year |
interval_count | integer | Number of intervals between billings |
currency | string | Three-letter ISO currency code (lowercase) |
amount | integer | Plan amount in cents |
Product Object (Nested)
| Field | Type | Description |
|---|---|---|
id | integer | Product ID |
name | string | Product display name |
name_internal | string | Internal product identifier |
Coupon Object (Nested)
| Field | Type | Description |
|---|---|---|
id | integer | Coupon ID |
name | string | Coupon display name |
code | string | Coupon code |
percent_off | integer | Percentage discount |
User Object (Nested)
| Field | Type | Description |
|---|---|---|
id | integer | Customer/user ID |
title | string | Professional title |
company | string | Company name |
first_name | string | First name |
last_name | string | Last name |
email | string | Email address |
Address Object (Nested in subscription)
| Field | Type | Description |
|---|---|---|
line1 | string | Street address line 1 |
line2 | string | Street address line 2 |
city | string | City |
state | string | State or province code |
country | string | Two-letter ISO country code |
postal_code | string | ZIP or postal code |
Campaign Types
| Type | Description |
|---|---|
Promotional | Marketing campaigns offering special deals or promotions |
Renewal | Automated reminders for upcoming subscription renewals |
Cancellation | Notifications when subscriptions are being canceled |
Creation | Notifications for newly created subscriptions |
Campaign Actions
| Action | Description |
|---|---|
Notification | Send webhook notifications only |
Export | Generate export file only |
Both | Send notifications and generate export |
Renewal | Process subscription renewals |
Cancellation | Process subscription cancellations |
Cancellation And Export | Process cancellations and generate export |
Creation | Process subscription creations |
Creation And Export | Process creations and generate export |
Related
- Webhooks Overview - Setup, signatures, and configuration
Updated about 22 hours ago