You can implement webhook integrations to receive real-time notifications about contact activities and list changes, which enables automated workflow triggers and better customer data synchronization across your marketing stack. This helps streamline your workflow by automatically updating external systems when subscriber data changes, reducing manual effort while maintaining data accuracy.
When properly configured, webhooks can enhance subscriber interaction by enabling immediate response to subscription changes and contact updates, leading to more timely and relevant customer communications.
Marketing Cloud enables you to integrate webhooks in two areas of the application: Settings and Contact Lists.
Webhook Integration in Settings
You can integrate webhooks in your account-level settings to get notified of any changes to the contacts. For detailed information, refer to our HTTP Post URL article.
Webhook Integration in Contact Lists
You can integrate webhooks in your lists to get notified of any changes to the subscription status of contacts in the lists. The webhook is fired when a contact is added to the list and also when the subscription status of contacts within the list changes.
When creating a new list or editing an existing list, enter the webhook API endpoint in the Post URL field.
When a new contact is added to the list (email + phone number), the webhook gets triggered twice as follows:
1st occurrence:
{
"subscriptions": [
{
"list_id": 3445,
"list": "sakshi test",
"status": "Subscribed",
"type": "sms"
}
],
"changed_attributes": {
"id": 213197,
"account_id": 1000,
"sms_list_id": null,
"sms_contact_id": null,
"active": true,
"created_at": "2026-07-28T07:08:30.000-04:00",
"updated_at": "2026-07-28T07:08:30.000-04:00",
"contact_id": 13485836,
"list_id": 3445,
"subscription_source": "sms"
},
"contact": {
"id": 13485836,
"account_id": 1000,
"email": "ss123_july@yopmail.com",
"first_name": "ss123",
"last_name": "acc1000",
"domain_name_id": 8924,
"created_at": "2026-07-28T07:08:30.000-04:00",
"updated_at": "2026-07-28T07:08:30.000-04:00",
"uid": "01KYM6JW1CTFP6H1ZYTX36TV4T",
"phone_number": "+918888666633",
},
"tags": []
}
2nd occurrence:
{
"subscriptions": [
{
"list_id": 3445,
"list": "sakshi test",
"status": "Subscribed",
"type": "email"
},
{
"list_id": 3445,
"list": "sakshi test",
"status": "Subscribed",
"type": "sms"
}
],
"changed_attributes": {
"id": 14849046,
"account_id": 1000,
"list_id": 3445,
"contact_id": 13485836,
"active": true,
"status": 0,
"created_at": "2026-07-28T07:08:30.000-04:00",
"updated_at": "2026-07-28T07:08:30.000-04:00",
"subscription_source": "list"
},
"contact": {
"id": 13485836,
"account_id": 1000,
"email": "ss123_july@yopmail.com",
"first_name": "ss123",
"last_name": "acc1000",
"domain_name_id": 8924,
"created_at": "2026-07-28T07:08:30.000-04:00",
"updated_at": "2026-07-28T07:08:31.000-04:00",
"uid": "01KYM6JW1CTFP6H1ZYTX36TV4T",
"phone_number": "+918888666633",
},
"tags": []
}
Subscription Source Behavior in the Webhook Payload
The changed_attributes.subscription_source attribute in the webhook payload indicates which subscription record triggered the webhook. It does not represent the contact's overall subscription state. For the contact's full email/SMS subscription state, refer to the subscriptions array (type: "email" / type: "sms").
Value | Meaning |
|---|
"list" | An email list subscription (ListSubscription) was created or updated. |
"sms" | An SMS list subscription (SmsSubscription) was created or updated. |
Observed behavior:
- Email only: The webhook fires with
subscription_source: "list". - SMS only: The webhook fires with
subscription_source: "sms". - Email + SMS: Typically two webhooks are sent, one per subscription type:
"list" for the email event and "sms" for the SMS event.
Example: Subscribed to Email Only
{
"subscriptions": [
{
"list_id": 6,
"list": "Manny Test List",
"status": "Subscribed",
"type": "email"
}
],
"changed_attributes": {
"id": 14849172,
"account_id": 1000,
"list_id": 6,
"contact_id": 13461949,
"active": true,
"status": 0,
"created_at": "2026-08-03T13:08:25.000-04:00",
"updated_at": "2026-08-03T13:08:25.000-04:00",
"subscription_source": "list"
}
}
Example: Subscribed to SMS Only
{
"subscriptions": [
{
"list_id": 6,
"list": "Manny Test List",
"status": "Subscribed",
"type": "sms"
}
],
"changed_attributes": {
"id": 213235,
"account_id": 1000,
"sms_list_id": null,
"sms_contact_id": null,
"active": true,
"created_at": "2026-08-03T13:10:58.000-04:00",
"updated_at": "2026-08-03T13:10:58.000-04:00",
"contact_id": 13485921,
"list_id": 6,
"subscription_source": "sms"
}
}
Example: Subscribed to Email and SMS
{
"subscriptions": [
{
"list_id": 6,
"list": "Manny Test List",
"status": "Subscribed",
"type": "email"
},
{
"list_id": 6,
"list": "Manny Test List",
"status": "Subscribed",
"type": "sms"
}
],
"changed_attributes": {
"id": 14849173,
"account_id": 1000,
"list_id": 6,
"contact_id": 13485922,
"active": true,
"status": 0,
"created_at": "2026-08-03T13:16:15.000-04:00",
"updated_at": "2026-08-03T13:16:15.000-04:00",
"subscription_source": "list"
}
}
Note: When a contact subscribes to both email and SMS in the same action, the two subscriptions are recorded as separate events, so you should expect a webhook for each.
Check subscription_source on each payload to determine which channel changed, and use the subscriptions array to see the contact's complete, current subscription state across both channels.
Ensuring Security When Using Webhooks
By default, Maropost does not include any authentication token in its webhook callbacks to your API endpoint. If you want to ensure stronger security, you can create a JSON Web Token that will then be included in all your webhook callbacks. The JSON Web Token can be created on the Connections page.
For more information on JSON Web Tokens and steps to create them, refer to our JSON Web Token (JWT) article.