Webhooks

Webhooks

Webhooks provide the ability to receive real-time data updates about your contact & campaign activity.

Choose to receive data based on certain actions (subscribes, unsubscribes, reads, etc..) and have all 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 the possible integration options like never before.

For information on APIs to create, update, and modify webhooks, see: Webhook API Documentation

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 could simply choose by the api as the only initiation option for your webhook. You can choose multiple initiation options if you wish.

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

 

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.

Please read further about how to work with webhook data.

 

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 data you can receive

You are able to pick the specific actions that you wish to receive data for. Each field option is sent as a POST parameter to your URL.

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
sms[phone] SMS recipient's phone number