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 |
| Campaign forwarded |
| Campaign opened |
| Campaign shared |
| Campaign starts sending |
| Contact added |
| Contact note added |
| Contact tag added |
| Contact tag removed |
| Contact unsubscription |
| Contact updated |
| Deal added |
| Deal note added |
| Deal pipeline added |
| Deal stage added |
| Deal task added |
| Deal task completed |
| Deal task type added |
| Deal updated |
| Email bounces |
| Email replies |
| Link clicked |
| List added |
| SMS reply |
| SMS sent |
| SMS unsubscribe |
Webhook sources
Source | Description |
| Run the hooks when a contact triggers the action |
| Run the hooks when an admin user triggers the action |
| Run the hooks when an API call triggers the action |
| Run the hooks when automated systems triggers the action |
Webhook payload fields
A new list is created
Field | Description |
| The webhook URL |
| list_add |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| Always set to 0 for this webhook. |
| New List ID |
| User ID who created this list |
| Name of this list |
| Street address line 1 |
| Street address line 2 |
| Street address city |
| Street address zip/postal code |
| Street address state |
| Street address country |
| Street full address (on a single line) |
| URL associated with this list |
| 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 |
| The webhook URL |
| subscribe |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| Always set to 0 for this webhook. |
| Subscription form ID (if applicable) |
| Contact system ID |
| Contact email address |
| Contact first name |
| Contact last name |
| Contact phone number (used for SMS) |
| Contact tags |
| Contact organization name (if plan allows) |
| Contact IP address |
An unsubscription occurs
Field | Description |
| The webhook URL |
| unsubscribe |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| List ID (if initiated from admin) |
| List ID (if initiated from public) |
| (Un)Subscription form ID (if applicable) |
| Campaign ID associated with the unsubscribe (if applicable) |
| Reason for unsubscribing (if supplied) |
| Contact system ID |
| Contact email address |
| Contact first name |
| Contact last name |
| Contact phone number (used for SMS) |
| Contact tags |
| Contact organization name (if plan allows) |
| Contact IP address |
| Contact custom fields. Where * is the custom field ID |
A contact's details are updated
Field | Description |
| The webhook URL |
| update |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| Always set to 0 for this webhook. |
| Contact system ID |
| Contact email address |
| Contact first name |
| Contact last name |
| Contact phone number (used for SMS) |
| Contact tags |
| Contact organization name (if plan allows) |
| Contact IP address |
| Contact custom fields. Where * is the custom field ID |
A new contact note is created
Field | Description |
| The webhook URL |
| subscriber_note |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| Always set to 0 for this webhook. |
| Note text |
| Contact system ID |
| Contact email address |
| Contact first name |
| Contact last name |
| Contact phone number (used for SMS) |
| Contact tags |
| Contact organization name (if plan allows) |
| Contact IP address |
| 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 |
| The webhook URL |
| sent |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| List ID or IDs associated with this campaign |
| Campaign ID |
| Campaign status |
| Total contacts |
| Type of campaign (single, RSS, etc) |
| The 'web copy' (social share) URL |
A campaign is opened by a contact
Field | Description |
| The webhook URL |
| open |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| List ID or IDs associated with this campaign |
| Campaign ID associated with the open |
| Contact system ID |
| Contact email address |
| Contact first name |
| Contact last name |
| Contact phone number (used for SMS) |
| Contact tags |
| Contact organization name (if plan allows) |
| Contact IP address |
| Contact custom fields. Where * is the custom field ID |
A campaign link was clicked by a contact
Field | Description |
| The webhook URL |
| click |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| List ID or IDs associated with this campaign |
| Campaign ID associated with the link click |
| Link system ID |
| Link URL (that was clicked) |
| Contact system ID |
| Contact email address |
| Contact first name |
| Contact last name |
| Contact phone number (used for SMS) |
| Contact tags |
| Contact organization name (if plan allows) |
| Contact IP address |
| Contact custom fields. Where * is the custom field ID |
A contact replies to a campaign
Field | Description |
| The webhook URL |
| reply |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| List ID or IDs associated with this campaign |
| Campaign ID associated with this reply |
| How we logged the message. ('forward','unsub','change','spam','challenge','vacation') |
| Full message source received |
| Contact system ID |
| Contact email address |
| Contact first name |
| Contact last name |
| Contact phone number (used for SMS) |
| Contact tags |
| Contact organization name (if plan allows) |
| Contact IP address |
| 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 |
| The webhook URL |
| forward |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| List ID or IDs associated with this campaign |
| Campaign ID associated with the forward |
| Total number of emails that were forwarded |
| Contact system ID |
| Contact email address |
| Contact first name |
| Contact last name |
| Contact phone number (used for SMS) |
| Contact tags |
| Contact organization name (if plan allows) |
| Contact IP address |
| Contact custom fields. Where * is the custom field ID |
A contact shares a campaign to Facebook or Twitter
Field | Description |
| The webhook URL |
| share |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| List ID or IDs associated with this campaign |
| Campaign ID associated with the share |
| Facebook or Twitter |
| Facebook or Twitter ID or username |
| Social network post content |
| Contact system ID |
| Contact email address |
| Contact first name |
| Contact last name |
| Contact phone number (used for SMS) |
| Contact tags |
| Contact organization name (if plan allows) |
| Contact IP address |
| Contact custom fields. Where * is the custom field ID |
A new bounce occurs after sending a campaign
Field | Description |
| The webhook URL |
| bounce |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| List ID associated with this contact |
| Campaign ID associated with the bounce |
| Type of bounce (hard or soft) |
| Bounce code |
| Bounce description |
| Contact system ID |
| Contact email address |
| Contact first name |
| Contact last name |
| Contact phone number (used for SMS) |
| Contact tags |
| Contact organization name (if plan allows) |
| Contact IP address |
| Contact custom fields. Where * is the custom field ID |
A new deal is created
Field | Description |
| The webhook URL |
| deal_add |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| Always set to 0 for this webhook. |
| The ID of the deal |
| The title of the deal |
| The creation date of the deal |
| The organization ID associated with the deal |
| The organization name associated with the deal |
| The stage ID associated with the deal |
| The stage title associated with the deal |
| The pipeline ID associated with the deal |
| The pipeline title associated with the deal |
| The value (dollar amount) of the deal |
| The currency (of the value) of the deal |
| The currency symbol of the value of the deal |
| The owner (user ID) of the deal |
| The owner (user) first name of the deal |
| The owner (used) last name of the deal |
| The contact ID associated with the deal |
| The contact email address associated with the deal |
| The contact first name associated with the deal |
| The contact last name associated with the deal |
| The status of the deal |
| Contact system ID |
| Contact email address |
| Contact first name |
| Contact last name |
| Contact phone number (used for SMS) |
| Contact tags |
| Contact organization name (if plan allows) |
| Contact IP address |
An existing deal is updated
Field | Description |
| The webhook URL |
| deal_update |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| Always set to 0 for this webhook. |
| The ID of the deal |
| The title of the deal |
| The creation date of the deal |
| The organization ID associated with the deal |
| The organization name associated with the deal |
| The stage ID associated with the deal |
| The stage title associated with the deal |
| The pipeline ID associated with the deal |
| The pipeline title associated with the deal |
| The value (dollar amount) of the deal |
| The currency (of the value) of the deal |
| The currency symbol of the value of the deal |
| The owner (user ID) of the deal |
| The owner (user) first name of the deal |
| The owner (used) last name of the deal |
| The contact ID associated with the deal |
| The contact email address associated with the deal |
| The contact first name associated with the deal |
| The contact last name associated with the deal |
| The status of the deal |
| The field names that were updated with the request |
A new deal note is created
Field | Description |
| The webhook URL |
| deal_note_add |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| Always set to 0 for this webhook. |
| The ID of the deal |
| The title of the deal |
| The creation date of the deal |
| The organization ID associated with the deal |
| The organization name associated with the deal |
| The stage ID associated with the deal |
| The stage title associated with the deal |
| The pipeline ID associated with the deal |
| The pipeline title associated with the deal |
| The value (dollar amount) of the deal |
| The currency (of the value) of the deal |
| The currency symbol of the value of the deal |
| The owner (user ID) of the deal |
| The owner (user) first name of the deal |
| The owner (used) last name of the deal |
| The contact ID associated with the deal |
| The contact email address associated with the deal |
| The contact first name associated with the deal |
| The contact last name associated with the deal |
| The status of the deal |
| The unique ID for the new note |
| The text for the new note |
A new deal pipeline is created
Field | Description |
| The webhook URL |
| deal_pipeline_add |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| Always set to 0 for this webhook. |
| The unique ID of the new pipeline |
| The title of the new pipeline |
A new deal stage is created
Field | Description |
| The webhook URL |
| deal_stage_add |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| Always set to 0 for this webhook. |
| The unique ID of the new stage |
| The title of the new stage |
| The header color of the new stage |
A new deal task is created
Field | Description |
| The webhook URL |
| deal_task_add |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| Always set to 0 for this webhook. |
| The ID of the deal |
| The title of the deal |
| The creation date of the deal |
| The organization ID associated with the deal |
| The organization name associated with the deal |
| The stage ID associated with the deal |
| The stage title associated with the deal |
| The pipeline ID associated with the deal |
| The pipeline title associated with the deal |
| The value (dollar amount) of the deal |
| The currency (of the value) of the deal |
| The currency symbol of the value of the deal |
| The owner (user ID) of the deal |
| The owner (user) first name of the deal |
| The owner (used) last name of the deal |
| The contact ID associated with the deal |
| The contact email address associated with the deal |
| The contact first name associated with the deal |
| The contact last name associated with the deal |
| The status of the deal |
| The unique ID of the new task |
| The task type ID of the new task |
| The note of the new task |
| The due date of the new task |
A new deal task type is created
Field | Description |
| The webhook URL |
| deal_tasktype_add |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| Always set to 0 for this webhook. |
| The unique ID of the new task type |
| The title of the new task type |
A new SMS message is sent
Field | Description |
| The webhook URL |
| sms_sent |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| Always set to 0 for this webhook. |
| Contact system ID |
| Contact email address |
| Contact first name |
| Contact last name |
| Contact phone number (used for SMS) |
| Contact tags |
| Contact organization name (if plan allows) |
| Contact IP address |
| Contact custom fields. Where * is the custom field ID |
| Unique system ID for this SMS message |
| SMS recipient's phone number |
| Whether or not the SMS was successfully sent (1 = yes, 0 = no) |
| Error response from SMS provider (if any) |
A SMS message is replied to
Field | Description |
| The webhook URL |
| sms_reply |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| Always set to 0 for this webhook. |
| Contact system ID |
| Contact email address |
| Contact first name |
| Contact last name |
| Contact phone number (used for SMS) |
| Contact tags |
| Contact organization name (if plan allows) |
| Contact IP address |
| Contact custom fields. Where * is the custom field ID |
| Unique system ID for this SMS message |
| Text included with the SMS message |
| Action taken as a result of the SMS message (example values: 'subscribe', 'forward', 'unsub', 'resub') |
A contact unsubscribes via SMS
Field | Description |
| The webhook URL |
| sms_unsub |
| Date/time that the webhook ran |
| Source/section of the software that triggered the webhook to run |
| Always set to 0 for this webhook. |
| Contact system ID |
| Contact email address |
| Contact first name |
| Contact last name |
| Contact phone number (used for SMS) |
| Contact tags |
| Contact organization name (if plan allows) |
| Contact IP address |
| Contact custom fields. Where * is the custom field ID |
| Unique system ID for this SMS message |