Using the Webhooks App in ContactDrive

The modern internet is built on interconnectivity, and ContactDrive is dedicated to helping you get all of your data all in one place.

With that bold mission in mind, our Webhooks app gives you the power to pull in data from almost any online platform, and push out to other tools you use — all in real time.

How to unlock this automation transformation? Let's get into it.

What is a webhook?

In the traditional web world, if you want to know if something happened (like if a customer paid an invoice), your application has to keep asking the server: "Is it done yet? How about now?" This is called polling.

A webhook reverses that. Instead of you asking, the other service automatically sends a "push" notification to your application the second the event occurs.

It’s like a digital SMS sent from one app to another.

How do webhooks work in ContactDrive?

We use webhooks to automate pulling data into ContactDrive and pushing it to other services.

If you have services that generate data, like form builders or donation platforms, odds are that they have a "webhooks" feature.

To get started build your webhook-powered pipeline, first add the Webhooks App to your workspace.

Once you have enabled Webhooks, you will find it under the Apps icon on your left sidebar.

When you setup an inbound webhook (where data is pushed to ContactDrive from another service), it will add or update a contact in your workspace and create a new activity item.

We like adding activity to each webhook / form submission because it adds clarity to the source of the contact, and you can save all the good metadata from a form submission, like UTM parameters.

NOTE: All webhooks come with API key security, which means inbound webhooks must be passed with an API key.

Setting up inbound webhooks

From the Webhooks app dashboard, click Add a Webhook to get started.

Create your Inbound Webhook

Fill out the following details:

Webhook Type: Select Inbound
Name: Best practice is to name it after the specific service and/or site were you will use it.
Activity Type: This is an optional field, but it does allow you to automatically associate any inbound submissions from this webhook with a specific type of activity, which makes the setup more consistent. Otherwise, you can set the activity in the submission parameters, or it will fallback to a default "action" activity type. Which isn't bad, it's just not ... special.
Description: It's there if you have any notes on the configuration to make sure your teammates see, or you'd just not rather forget.

Once you've saved the form, you will now see it under the "Inbound" tab on your Webhooks dashboard. From there, you can copy the URL that you can paste into the other service you are connecting, edit the webhook details, or delete it all together.

REQUIRED STEP: Secure your webhook with an API key

There is one pseudo-technical step to setting up a webhook, and that is creating an API key to go with it.

Once you have copied your webhook, go to your workspace Settings, then API Keys. Create a new key and label it so you know it is associated with the webhook.

Then copy this API key and combine it with the webhook URL, using the text ?apiKey=

So your final webhook URL should look like:

https://CONTACTDRIVE_URL_FROM_THE_APP?apiKey=API_KEY_FROM_SETTINGS

Map webhook data fields

In most services that provide outbound webhooks, you are able to map the fields from that service to a specific schema of field names, so they map easily to the destination platform (e.g. ContactDrive).

Below is a list of the field names available in ContactDrive you can use to map whatever fields you are getting from the source service.

Contact fields

cdId : A contact's unique ID on the ContactDrive platform
prefix : "Mr.", "Mrs.", "Dr.", "The Honorable", etc
firstName
middleName
lastName
suffix
nickname
fullname
organization : Use this field name for employer, company name, etc.
jobTitle : Use this for occupation, etc.
tags : Best if sent as a comma-separated string
workEmail
homeEmail
otherEmail
mobilePhone
workPhone
homePhone
otherPhone
workStreet
workStreet2
workCity
workCounty
workState
workZip
workCountry
homeStreet
homeStreet2
homeCity
homeCounty
homeState
homeZip
homeCountry
otherStreet
otherStreet2
otherCity
otherCounty
otherState
otherZip
otherCountry
notes
birthdate
gender
rating
website
doNotContact : must be "true" or "false"

Activity fields

activityDate : Usually a "created at" date from the source service
activityType : One of your workspace's activity types (action, transaction, email, event, sms, etc). Leave blank to use the default activity type configured with this webhook.
activityAction : This one trips people up. activityAction is the message that appears on an activity post next to the contact's name, so it needs to read like the end of a sentence. e.g., "filled out the Volunteer form" or "made a donation". Note that this can be configured for any default or custom activity types in your workspace settings.
activityMessage : The content of an activity post message, often a comment or other collection of data.
Custom Fields: To map data from an inbound webhook to a custom field, use the custom field slug found on your workspace Settings > Custom Fields.
External IDs: The following custom IDs are specifically available to use in inbound webhooks:
- emailoctopus_emailId : EmailOctopus List_Contact
- datatrust_regId : DataTrust Reg ID
- i360_contactId : i360 Contact ID
- i360_uid : i360 UID
- l2_voterId : L2 Voter ID
- nationbuilder_contactId : NationBuilder ID
- salesforce_salesforceId : Salesforce ID
- state_voterId : A state voter ID in the format state_voterId (e.g. OH_abc123 )
- You can also map any custom field marked as a Unique ID, and that field will be used to help match inbound webhooks with existing contacts.

Setting up outbound webhooks

Let's say you want data to go the opposite direction: sending from ContactDrive to some other service. You're in luck! You can also do this right in the Webhooks app.