API explorerChangelog
Overview

Sections

API explorer
Changelog

Theme switcher

Create new subscription

This method allows you to create a new webhook subscription. You can subscribe to one or more of the available event types associated with the supported entities. Click here to see the complete list of supported event types.

Before creating a webhook subscription, you must contact support to enable Events on your account. Once enabled, your receiving endpoint must respond with the expected validation payload to complete the handshake process and begin accepting incoming event notifications.

Refer to the sample window on the right for subscription examples across different entities.

Using the same webhook URL to subscribe to the same event in multiple subscriptions is not allowed. Doing so will result in the API returning a 409-Conflict status code.

Sample Webhook Subscription Request

The following sample demonstrates how to submit an event subscription request. It's important to note that certain entities support event generation across all their instances. For example, to receive notifications whenever a preference is added to any filter in your MyPreferences account, include 'AllFilters' in the Filters array when subscribing to the preference.added event. If you prefer to receive events for only specific filters, provide the corresponding filter IDs in the Filters array instead.

  • Preferences : [AllFilters]
  • Consents: [AllConsents]
  • Contacts: [AllContactTypes]
  • Groups: [AllGroups]
  • Custom Fields: [AllCustomFields]
Plain text
{
	"Name": "Webhook - Consent and Preference Updates",
	"Description": "consent and preference data updates",
	"LocaleID": "en_US",
	"Url": "https://eowju7xe3jismp9.m.mywehookURL.net/",
	"Subscriptions": [
		{
			"Entity": "Contacts",
			"EventType": "contacts.alternateid.added",
			"ContactTypes": [
				"AllContactTypes"
			]
		},
		{
			"Entity": "Consents",
			"EventType": "consent.added",
			"ConsentTypes": [
				"AllConsents"
			]
		},
		{
			"Entity": "Consents",
			"EventType": "consent.deactivated",
			"ConsentTypes": [
				"AllConsents"
			]
		},
		{
			"Entity": "Consents",
			"EventType": "consent.elementassociation.created",
			"ConsentTypes": [
				"AllConsents"
			]
		},
		{
			"Entity": "Consents",
			"EventType": "consent.elementassociation.updated",
			"ConsentTypes": [
				"AllConsents"
			]
		},
		{
			"Entity": "Consents",
			"EventType": "consent.filterassociation.created",
			"ConsentTypes": [
				"AllConsents"
			]
		},
		{
			"Entity": "Consents",
			"EventType": "consent.filterassociation.updated",
			"ConsentTypes": [
				"AllConsents"
			]
		},
		{
			"Entity": "Consents",
			"EventType": "consent.elementassociation.deactivated",
			"ConsentTypes": [
				"AllConsents"
			]
		},
		{
			"Entity": "Consents",
			"EventType": "consent.filterassociation.deactivated",
			"ConsentTypes": [
				"AllConsents"
			]
		},
		{
			"Entity": "Consents",
			"EventType": "consent.updated",
			"ConsentTypes": [
				"AllConsents"
			]
		},
		{
			"Entity": "Contacts",
			"EventType": "contacts.address.added",
			"ContactTypes": [
				"AllContactTypes"
			]
		},
		{
			"Entity": "Contacts",
			"EventType": "contacts.address.deleted",
			"ContactTypes": [
				"AllContactTypes"
			]
		},
		{
			"Entity": "Contacts",
			"EventType": "contacts.address.updated",
			"ContactTypes": [
				"AllContactTypes"
			]
		},
		{
			"Entity": "Contacts",
			"EventType": "contacts.email.added",
			"ContactTypes": [
				"AllContactTypes"
			]
		},
		{
			"Entity": "Contacts",
			"EventType": "contacts.email.deleted",
			"ContactTypes": [
				"AllContactTypes"
			]
		},
		{
			"Entity": "Contacts",
			"EventType": "contacts.email.updated",
			"ContactTypes": [
				"AllContactTypes"
			]
		},
		{
			"Entity": "Contacts",
			"EventType": "contacts.phone.updated",
			"ContactTypes": [
				"Personal",
				"Work"
			]
		},
		{
			"Entity": "CustomFields",
			"EventType": "customfield.added",
			"CustomFields": [
				"AllCustomFields"
			]
		},
		{
			"Entity": "CustomFields",
			"EventType": "customfield.deleted",
			"CustomFields": [
				"AllCustomFields"
			]
		},
		{
			"Entity": "CustomFields",
			"EventType": "customfield.updated",
			"CustomFields": [
				"AllCustomFields"
			]
		},
		{
			"Entity": "Groups",
			"EventType": "group.added",
			"Groups": [
				"AllGroups"
			]
		},
		{
			"Entity": "Groups",
			"EventType": "group.deactivated",
			"Groups": [
				"AllGroups"
			]
		},
		{
			"Entity": "Groups",
			"EventType": "group.updated",
			"Groups": [
				"AllGroups"
			]
		},
		{
			"Entity": "Preferences",
			"EventType": "preference.added",
			"Filters": [
				"AllFilters"
			]
		},
		{
			"Entity": "Preferences",
			"EventType": "preference.archived",
			"Filters": [
				"AllFilters"
			]
		},
		{
			"Entity": "Preferences",
			"EventType": "preference.updated",
			"Filters": [
				"AllFilters"
			]
		},
		{
			"Entity": "ProfileActions",
			"EventType": "profile.created"
		},
		{
			"Entity": "ProfileActions",
			"EventType": "profile.updated"
		},
		{
			"Entity": "ProfileActions",
			"EventType": "profile.deleted"
		},
		{
			"Entity": "Tags",
			"EventType": "tag.added"
		},
		{
			"Entity": "Tags",
			"EventType": "tag.deleted"
		},
		{
			"Entity": "StandardFields",
			"EventType": "standardfield.defaultlocale.updated"
		},
		{
			"Entity": "StandardFields",
			"EventType": "standardfield.registrationstatus.updated"
		}
	],
	"IsMinimized": false,
	"State": "Active",
	"IsActive": true
}

Header Parameters

Authorizationstring Required

Authorization token

Content-Typestring

Type of the data being sent in the request or the data that is expected in the response. Supports application/json.

Path Parameters

clientIdstring Required

This is your organization’s MyPreferences account Id.

Body Parameters

Namestring Required

Name of the subscription.

Descriptionstring

Description of the subscription.

LocaleIdstring

LocaleId used to return localized name and description for the event.

Urlstring Required

URL associated with the subscription to receive POST requests for events. Only secure (htttps) URL's are supported

Statestring

The status of the subscription whether it's active and sending notifications, paused, or inactive. If you don't specify a state with your request, the default state of "Paused" will be applied.

Enum values:
Active
he webhook subscription is currently enabled and delivering events to the configured endpoint.
Paused
The webhook subscription is temporarily disabled and will not send any events until reactivated.
IsMinimizedboolean

If set to true, the event notifications will only include the main event information without any data associated with it. Receiving systems must retrieve the data by other means.

IsActiveboolean

Indicates whether the webhook subscription is active or not. Deactivating a subscription will result in its deletion. Please deactivate a subscription only when you no longer wish to receive event notifications. If you wish to temporarily pause event notifications, you can achieve this by using the 'State' parameter and setting it to 'Paused'.

CatchUpOnResumeboolean

If set to true, the system delivers events generated during the paused period, up to a maximum of 15 days, prior to resumption.

Subscriptionsarray Required

Collection of event subscriptions. Check out subscription examples for various entities in the upper right corner.

Show child attributes

AlternateIdTypestring

Type Name associated with an active AlternateId Type. If available, will be returned instead of the profileId.

Response

201
Object
The request was successful and resulted in the creation of a new webhook subscription.

Response Attributes

Idnumber

System generated read-only value that uniquely identifies the webhook subscription.

Namestring

Name of the webhook subscription.

Descriptionstring

Description of the webhook subscription

LocaleIdstring

LocaleId used to return localized name and description for the event.

Urlstring

Url associated with the subscription to receive HTTP POST requests. Only HTTPS URL's are supported.

Subscriptionsarray

Collection of event subscriptions.

Show child attributes

Statestring

The status of the subscription whether it's active and sending notifications, paused, or inactive.

IsMinimizedstring

If set to true, the event notifications will only include the main event information without any data associated with it. Receiving systems must retrieve the data by other means.

IsActiveboolean

Indicates whether the webhook subscription is active or not.

AlternateIdTypestring

Type Name associated with an active AlternateId Type. If available, will be returned instead of the profileId.

400
Object
The request was invalid and cannot be processed. This may be a result of a malformed request. You must update the request before trying again.
401
Object
Authentication credentials are missing or incorrect. You must verify your ClientId, UserId, and Authorization Scheme before trying again.
403
Object
The authentication credentials were insufficient to grant access to the requested resource. In most cases, your user may not have the appropriate permissions to access the requested resource. Verify User Group permissions for your user before trying again.
503
Object
The server encountered an unexpected condition that prevented it from fulfilling the request. Notify PossibleNOW Support if it’s a continuous occurrence.

Tags

Entitystring Required

The object or resource associated with the event (e.g., Preference, Consent, Custom Field, etc.).

Enum values:
Tags
EventTypestring

The specific type of event you are subscribing to (e.g., preference.added, customfield.updated)

Contacts

Entitystring Required
Enum values:
Contacts
EventTypestring
ContactTypesarray

Show child attributes

Profile

Entitystring Required
Enum values:
ProfileActions
EventTypestring

Preferences

Entitystring Required
Enum values:
Preferences
EventTypestring
Filtersarray Required

Filter ID's associated with the Filters you want to subscribe. When subscribing to all Filters, specify 'AllFilters'

Min items
1

Show child attributes

StandardFields

Entitystring Required
Enum values:
StandardFields
EventTypestring

Consents

Entitystring Required
Enum values:
Consents
EventTypestring
ConsentTypesarray Required

Type Names of the Consents you want to subscribe. When subscribing to all Consents, specify 'AllConsents'

Min items
1

Show child attributes

Groups

Entitystring Required
Enum values:
Groups
EventTypestring
Groupsarray Required

Names of the Groups you want to subscribe. When subscribing to all Groups, specify 'AllGroups'

Min items
1

Show child attributes

CustomFields

Entitystring Required
Enum values:
CustomFields
EventTypestring
CustomFieldsarray Required

Names of the custom fields you want to subscribe. When subscribing to all custom fields, specify 'AllCustomFields'

Min items
1

Show child attributes

Was this section helpful?

What made this section unhelpful for you?

1 2 3 4 { "Entity": "Tags", "EventType": "tag.added" }

POST

/

Select
1

Response

Was this section helpful?

What made this section unhelpful for you?