Skip to main content
Webhooks
M
Written by Martyna Woźniszczuk
Updated over 2 years ago

Webhooks provide the ability to receive real-time data updates about your various CDXP events as well as contact and campaign activity.

You may choose to receive data based on certain actions (contact subscribes, contact unsubscribes, campaign opens, deal adds, SMS sends, etc..) and have applicable data sent to a URL of your choice. You can then use your own custom script to read, save, and do whatever you want with that data. This is a powerful option that allows you to keep all of your data in sync and opens up various integration options.

Choose when a webhook should run

With every webhook you create, you can choose when it should actually fire. Perhaps you only want to receive data when a contact is subscribed from the API. You can simply specify subscribe as the event and API as the source when you create your webhook. You can specify multiple events and sources for each webhook if you wish. All event and source options are listed below.

We guarantee at least once delivery on webhooks. In some rare cases, you may receive a webhook event more than once, so it’s important to create an idempotent system.

Processing webhook data

Any programming language can read webhook data, which comes across as post data to any URL. For example, use the $_POST variable in PHP. If you need to access webhook data behind a firewall, we have tested and find UltraHook (third-party utility) very easy to set up and use.

Automatic Webhook Deactivation

Webhooks will be automatically set to a state of inactive if they return an HTTP 410 (gone) response.

Deactivated webhooks will still show up in the UI, but they will not send. To reactivate a webhook, delete it and recreate it.

Initiation options

Option

Description

By a contact

Run hooks when a contact causes the action (IE: subscribes, opens a campaign, etc..)

By an admin user

Run the hooks when an admin user causes the action (IE: adding a contact from the admin area)

By system processes

Run the hooks when automated systems cause the action (IE: bounces, automated campaigns, etc..)

By the API

Run the hooks when an API call causes the action (IE: adding a contact using the contact_add API call)

Webhook events and sources

Events

Event

Description

forward

Campaign forwarded

open

Campaign opened

share

Campaign shared

sent

Campaign starts sending

subscribe

Contact added

subscriber_note

Contact note added

contact_tag_added

Contact tag added

contact_tag_removed

Contact tag removed

unsubscribe

Contact unsubscription

update

Contact updated

deal_add

Deal added

deal_note_add

Deal note added

deal_pipeline_add

Deal pipeline added

deal_stage_add

Deal stage added

deal_task_add

Deal task added

deal_task_complete

Deal task completed

deal_tasktype_add

Deal task type added

deal_update

Deal updated

bounce

Email bounces

reply

Email replies

click

Link clicked

list_add

List added

sms_reply

SMS reply

sms_sent

SMS sent

sms_unsub

SMS unsubscribe

Webhook sources

Source

Description

public

Run the hooks when a contact triggers the action

admin

Run the hooks when an admin user triggers the action

api

Run the hooks when an API call triggers the action

system

Run the hooks when automated systems triggers the action

Webhook payload fields

A new list is created

Field

Description

url

The webhook URL

type

list_add

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

Always set to 0 for this webhook.

list[id]

New List ID

list[userid]

User ID who created this list

list[name]

Name of this list

list[sender_addr1]

Street address line 1

list[sender_addr2]

Street address line 2

list[sender_city]

Street address city

list[sender_zip]

Street address zip/postal code

list[sender_state]

Street address state

list[sender_country]

Street address country

list[fulladdress]

Street full address (on a single line)

list[sender_url]

URL associated with this list

list[sender_reminder]

Reminder to contacts for this list (why you are emailing them)

A new contact is subscribed

This hook will not run during mass inserts such as contact imports.

Field

Description

url

The webhook URL

type

subscribe

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

Always set to 0 for this webhook.

form[id]

Subscription form ID (if applicable)

contact[id]

Contact system ID

contact[email]

Contact email address

contact[first_name]

Contact first name

contact[last_name]

Contact last name

contact[phone]

Contact phone number (used for SMS)

contact[tags]

Contact tags

contact[orgname]

Contact organization name (if plan allows)

contact[ip]

Contact IP address

An unsubscription occurs

Field

Description

url

The webhook URL

type

unsubscribe

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

List ID (if initiated from admin)

list[][id]

List ID (if initiated from public)

form[id]

(Un)Subscription form ID (if applicable)

campaign[id]

Campaign ID associated with the unsubscribe (if applicable)

unsubscribe[reason]

Reason for unsubscribing (if supplied)

contact[id]

Contact system ID

contact[email]

Contact email address

contact[first_name]

Contact first name

contact[last_name]

Contact last name

contact[phone]

Contact phone number (used for SMS)

contact[tags]

Contact tags

contact[orgname]

Contact organization name (if plan allows)

contact[ip]

Contact IP address

contact[fields][*]

Contact custom fields. Where * is the custom field ID

A contact's details are updated

Field

Description

url

The webhook URL

type

update

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

Always set to 0 for this webhook.

contact[id]

Contact system ID

contact[email]

Contact email address

contact[first_name]

Contact first name

contact[last_name]

Contact last name

contact[phone]

Contact phone number (used for SMS)

contact[tags]

Contact tags

contact[orgname]

Contact organization name (if plan allows)

contact[ip]

Contact IP address

contact[fields][*]

Contact custom fields. Where * is the custom field ID

A new contact note is created

Field

Description

url

The webhook URL

type

subscriber_note

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

Always set to 0 for this webhook.

note

Note text

contact[id]

Contact system ID

contact[email]

Contact email address

contact[first_name]

Contact first name

contact[last_name]

Contact last name

contact[phone]

Contact phone number (used for SMS)

contact[tags]

Contact tags

contact[orgname]

Contact organization name (if plan allows)

contact[ip]

Contact IP address

contact[fields][*]

Contact custom fields. Where * is the custom field ID

A campaign starts sending

Campaigns triggered by Events, such as Autoresponder Campaigns and Automation driven Campaigns, will not trigger webhooks.

Field

Description

url

The webhook URL

type

sent

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

List ID or IDs associated with this campaign

campaign[id]

Campaign ID

campaign[status]

Campaign status

campaign[recipients]

Total contacts

campaign[type]

Type of campaign (single, RSS, etc)

campaign[webcopy_url]

The 'web copy' (social share) URL

A campaign is opened by a contact

Field

Description

url

The webhook URL

type

open

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

List ID or IDs associated with this campaign

campaign[id]

Campaign ID associated with the open

contact[id]

Contact system ID

contact[email]

Contact email address

contact[first_name]

Contact first name

contact[last_name]

Contact last name

contact[phone]

Contact phone number (used for SMS)

contact[tags]

Contact tags

contact[orgname]

Contact organization name (if plan allows)

contact[ip]

Contact IP address

contact[fields][*]

Contact custom fields. Where * is the custom field ID

A campaign link was clicked by a contact

Field

Description

url

The webhook URL

type

click

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

List ID or IDs associated with this campaign

campaign[id]

Campaign ID associated with the link click

link[id]

Link system ID

link[url]

Link URL (that was clicked)

contact[id]

Contact system ID

contact[email]

Contact email address

contact[first_name]

Contact first name

contact[last_name]

Contact last name

contact[phone]

Contact phone number (used for SMS)

contact[tags]

Contact tags

contact[orgname]

Contact organization name (if plan allows)

contact[ip]

Contact IP address

contact[fields][*]

Contact custom fields. Where * is the custom field ID

A contact replies to a campaign

Field

Description

url

The webhook URL

type

reply

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

List ID or IDs associated with this campaign

campaign[id]

Campaign ID associated with this reply

result

How we logged the message. ('forward','unsub','change','spam','challenge','vacation')

message

Full message source received

contact[id]

Contact system ID

contact[email]

Contact email address

contact[first_name]

Contact first name

contact[last_name]

Contact last name

contact[phone]

Contact phone number (used for SMS)

contact[tags]

Contact tags

contact[orgname]

Contact organization name (if plan allows)

contact[ip]

Contact IP address

contact[fields][*]

Contact custom fields. Where * is the custom field ID

A contact forwards a campaign (through our forward link)

This won't work if the contact uses their email client's Forward option.

Field

Description

url

The webhook URL

type

forward

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

List ID or IDs associated with this campaign

campaign[id]

Campaign ID associated with the forward

forward[count]

Total number of emails that were forwarded

contact[id]

Contact system ID

contact[email]

Contact email address

contact[first_name]

Contact first name

contact[last_name]

Contact last name

contact[phone]

Contact phone number (used for SMS)

contact[tags]

Contact tags

contact[orgname]

Contact organization name (if plan allows)

contact[ip]

Contact IP address

contact[fields][*]

Contact custom fields. Where * is the custom field ID

A contact shares a campaign to Facebook or Twitter

Field

Description

url

The webhook URL

type

share

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

List ID or IDs associated with this campaign

campaign[id]

Campaign ID associated with the share

share[network]

Facebook or Twitter

share[network_id]

Facebook or Twitter ID or username

share[content]

Social network post content

contact[id]

Contact system ID

contact[email]

Contact email address

contact[first_name]

Contact first name

contact[last_name]

Contact last name

contact[phone]

Contact phone number (used for SMS)

contact[tags]

Contact tags

contact[orgname]

Contact organization name (if plan allows)

contact[ip]

Contact IP address

contact[fields][*]

Contact custom fields. Where * is the custom field ID

A new bounce occurs after sending a campaign

Field

Description

url

The webhook URL

type

bounce

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

List ID associated with this contact

campaign[id]

Campaign ID associated with the bounce

bounce[type]

Type of bounce (hard or soft)

bounce[code]

Bounce code

bounce[description]

Bounce description

contact[id]

Contact system ID

contact[email]

Contact email address

contact[first_name]

Contact first name

contact[last_name]

Contact last name

contact[phone]

Contact phone number (used for SMS)

contact[tags]

Contact tags

contact[orgname]

Contact organization name (if plan allows)

contact[ip]

Contact IP address

contact[fields][*]

Contact custom fields. Where * is the custom field ID

A new deal is created

Field

Description

url

The webhook URL

type

deal_add

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

Always set to 0 for this webhook.

deal[id]

The ID of the deal

deal[title]

The title of the deal

deal[create_date]

The creation date of the deal

deal[orgid]

The organization ID associated with the deal

deal[orgname]

The organization name associated with the deal

deal[stageid]

The stage ID associated with the deal

deal[stage_title]

The stage title associated with the deal

deal[pipelineid]

The pipeline ID associated with the deal

deal[pipeline_title]

The pipeline title associated with the deal

deal[value]

The value (dollar amount) of the deal

deal[currency]

The currency (of the value) of the deal

deal[currency_symbol]

The currency symbol of the value of the deal

deal[owner]

The owner (user ID) of the deal

deal[owner_firstname]

The owner (user) first name of the deal

deal[owner_lastname]

The owner (used) last name of the deal

deal[contactid]

The contact ID associated with the deal

deal[contact_email]

The contact email address associated with the deal

deal[contact_firstname]

The contact first name associated with the deal

deal[contact_lastname]

The contact last name associated with the deal

deal[status]

The status of the deal

contact[id]

Contact system ID

contact[email]

Contact email address

contact[first_name]

Contact first name

contact[last_name]

Contact last name

contact[phone]

Contact phone number (used for SMS)

contact[tags]

Contact tags

contact[orgname]

Contact organization name (if plan allows)

contact[ip]

Contact IP address

An existing deal is updated

Field

Description

url

The webhook URL

type

deal_update

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

Always set to 0 for this webhook.

deal[id]

The ID of the deal

deal[title]

The title of the deal

deal[create_date]

The creation date of the deal

deal[orgid]

The organization ID associated with the deal

deal[orgname]

The organization name associated with the deal

deal[stageid]

The stage ID associated with the deal

deal[stage_title]

The stage title associated with the deal

deal[pipelineid]

The pipeline ID associated with the deal

deal[pipeline_title]

The pipeline title associated with the deal

deal[value]

The value (dollar amount) of the deal

deal[currency]

The currency (of the value) of the deal

deal[currency_symbol]

The currency symbol of the value of the deal

deal[owner]

The owner (user ID) of the deal

deal[owner_firstname]

The owner (user) first name of the deal

deal[owner_lastname]

The owner (used) last name of the deal

deal[contactid]

The contact ID associated with the deal

deal[contact_email]

The contact email address associated with the deal

deal[contact_firstname]

The contact first name associated with the deal

deal[contact_lastname]

The contact last name associated with the deal

deal[status]

The status of the deal

updated_fields[*]

The field names that were updated with the request

A new deal note is created

Field

Description

url

The webhook URL

type

deal_note_add

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

Always set to 0 for this webhook.

deal[id]

The ID of the deal

deal[title]

The title of the deal

deal[create_date]

The creation date of the deal

deal[orgid]

The organization ID associated with the deal

deal[orgname]

The organization name associated with the deal

deal[stageid]

The stage ID associated with the deal

deal[stage_title]

The stage title associated with the deal

deal[pipelineid]

The pipeline ID associated with the deal

deal[pipeline_title]

The pipeline title associated with the deal

deal[value]

The value (dollar amount) of the deal

deal[currency]

The currency (of the value) of the deal

deal[currency_symbol]

The currency symbol of the value of the deal

deal[owner]

The owner (user ID) of the deal

deal[owner_firstname]

The owner (user) first name of the deal

deal[owner_lastname]

The owner (used) last name of the deal

deal[contactid]

The contact ID associated with the deal

deal[contact_email]

The contact email address associated with the deal

deal[contact_firstname]

The contact first name associated with the deal

deal[contact_lastname]

The contact last name associated with the deal

deal[status]

The status of the deal

note[id]

The unique ID for the new note

note[text]

The text for the new note

A new deal pipeline is created

Field

Description

url

The webhook URL

type

deal_pipeline_add

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

Always set to 0 for this webhook.

pipeline[id]

The unique ID of the new pipeline

pipeline[title]

The title of the new pipeline

A new deal stage is created

Field

Description

url

The webhook URL

type

deal_stage_add

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

Always set to 0 for this webhook.

stage[id]

The unique ID of the new stage

stage[title]

The title of the new stage

stage[color]

The header color of the new stage

A new deal task is created

Field

Description

url

The webhook URL

type

deal_task_add

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

Always set to 0 for this webhook.

deal[id]

The ID of the deal

deal[title]

The title of the deal

deal[create_date]

The creation date of the deal

deal[orgid]

The organization ID associated with the deal

deal[orgname]

The organization name associated with the deal

deal[stageid]

The stage ID associated with the deal

deal[stage_title]

The stage title associated with the deal

deal[pipelineid]

The pipeline ID associated with the deal

deal[pipeline_title]

The pipeline title associated with the deal

deal[value]

The value (dollar amount) of the deal

deal[currency]

The currency (of the value) of the deal

deal[currency_symbol]

The currency symbol of the value of the deal

deal[owner]

The owner (user ID) of the deal

deal[owner_firstname]

The owner (user) first name of the deal

deal[owner_lastname]

The owner (used) last name of the deal

deal[contactid]

The contact ID associated with the deal

deal[contact_email]

The contact email address associated with the deal

deal[contact_firstname]

The contact first name associated with the deal

deal[contact_lastname]

The contact last name associated with the deal

deal[status]

The status of the deal

task[id]

The unique ID of the new task

task[type_id]

The task type ID of the new task

task[note]

The note of the new task

task[duedate]

The due date of the new task

A new deal task type is created

Field

Description

url

The webhook URL

type

deal_tasktype_add

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

Always set to 0 for this webhook.

tasktype[id]

The unique ID of the new task type

tasktype[title]

The title of the new task type

A new SMS message is sent

Field

Description

url

The webhook URL

type

sms_sent

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

Always set to 0 for this webhook.

contact[id]

Contact system ID

contact[email]

Contact email address

contact[first_name]

Contact first name

contact[last_name]

Contact last name

contact[phone]

Contact phone number (used for SMS)

contact[tags]

Contact tags

contact[orgname]

Contact organization name (if plan allows)

contact[ip]

Contact IP address

contact[fields][*]

Contact custom fields. Where * is the custom field ID

sms[id]

Unique system ID for this SMS message

sms[recipient]

SMS recipient's phone number

sms[successful]

Whether or not the SMS was successfully sent (1 = yes, 0 = no)

sms[comment]

Error response from SMS provider (if any)

A SMS message is replied to

Field

Description

url

The webhook URL

type

sms_reply

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

Always set to 0 for this webhook.

contact[id]

Contact system ID

contact[email]

Contact email address

contact[first_name]

Contact first name

contact[last_name]

Contact last name

contact[phone]

Contact phone number (used for SMS)

contact[tags]

Contact tags

contact[orgname]

Contact organization name (if plan allows)

contact[ip]

Contact IP address

contact[fields][*]

Contact custom fields. Where * is the custom field ID

sms[id]

Unique system ID for this SMS message

sms[reply]

Text included with the SMS message

sms[result]

Action taken as a result of the SMS message (example values: 'subscribe', 'forward', 'unsub', 'resub')

A contact unsubscribes via SMS

Field

Description

url

The webhook URL

type

sms_unsub

date_time

Date/time that the webhook ran

initiated_by

Source/section of the software that triggered the webhook to run

list

Always set to 0 for this webhook.

contact[id]

Contact system ID

contact[email]

Contact email address

contact[first_name]

Contact first name

contact[last_name]

Contact last name

contact[phone]

Contact phone number (used for SMS)

contact[tags]

Contact tags

contact[orgname]

Contact organization name (if plan allows)

contact[ip]

Contact IP address

contact[fields][*]

Contact custom fields. Where * is the custom field ID

sms[id]

Unique system ID for this SMS message

Did this answer your question?