Marketo webhooks are a powerful way to interact with 3rd party systems in order to unlock a range of functionality that cannot be achieved in Marketo. This post will give you a deep dive into how webhooks are set up, how you can use them in different use cases, and how to debug them if you are getting issues.
What is a Webhook?
A webhook is a mechanism that will allow you to interact with 3rd party systems by sending information from Marketo to a particular URL in order to retrieve information from these systems or to make updates to these systems.
Here are some example use cases where webhooks can be used:
- Sending messages to Slack from Marketo
- Triggering a workflow to run in Zapier
- Sending SMS messages to your customers
- Routing leads within Salesforce
- Enriching leads with information from phone number lookups
- Enriching leads with Clearbit information
- Doing calculations with field values and storing the result (see the "Field Calculations with Marketo Webhooks" section below)
Webhook Configuration
Here is a quick explanation of all the settings that will need to be configured when creating a webhook in Marketo. The documentation from the 3rd party should tell you what URL to send the webhook to, what encoding to use, what the request type should be, and what format the response will be in.
- The "URL" field should contain the URL of the 3rd party endpoint that you want to send the Marketo webook to. Similar to the "Payload" template it is possible to use tokens within this URL, which is important for some requests where the URL needs to change based on a token e.g. a person's phone number to send them an SMS.
Lead token in URL
- The "Payload Template" contains the information that you want to send in the webhook. As you will see in the "Using Tokens in Marketo Webhooks" section below you can populate this payload with lead, trigger, system, and campaign tokens.
Lead Tokens in Payload Template
- The "Request Token Encoding" option is usually set to "None", however there are some cases where the tokens you use in the "URL" or "Payload Template" fields will need to be encoded to be sent successfully e.g. when they contain special characters like ampersands.If you are not sure whether to use encoding then I recommend starting with "None" and then if you get errors because of invalid payloads or issues with the URL then look into using "JSON" or "Form/URL" encoding, hopefully the 3rd party documentation will tell you which of these 2 formats they expect the data to be in.
- Most often the "Request Type" will either be "POST" if you are sending information to a 3rd party to make a change or update in their system or "GET" when you want to retrieve information from their system. I have made many a webhook in my time and I have yet to come across the need to use the "DELETE", "PATCH", or "PUT" request types.
- The "Response Format" only matters when you are using a "GET" request and plan on storing the information returned from the 3rd party. You can leave this as "None" if the request you are making is not a "GET" request.
- Sometimes you might need to set a "Custom Header" for your webhook which will contain extra information that the 3rd party needs in order to process the webhook. For example, you might need to provide authorization in the header or specify the type of content you are sending over.
Custom Header
Creating a Webhook
Now that you understand the configuration of a Marketo webhook you can follow the steps below to create one:
- Navigate to the Admin section in Marketo
- Click on “Webhooks” under the “Integration” section in the navigation tree on the left hand side
- Click on “New Webhook” at the top of the screen
- Name your webhook using the “Webhook Name” field
- Enter an optional description if you desire
- Paste the URL of the 3rd party endpoint that you want to send the webhook to in the “URL” field
- Choose the “Request Type”
- What you put in the “Template” field will depend on the information you are trying to send to the 3rd party (see the "Using Tokens in Marketo Webhooks" section below)
- Leave the “Request Token Encoding” field as "None" unless the 3rd party documentation indicates otherwise or you are getting errors related to invalid payloads or issues with the destination URL when you are using tokens in the payload or the destination URL.
- Leave the “Response type” field as “None” if the "Request Type" is not "GET" . If the "Request Type" is "GET" then consult the 3rd party documentation to see if the data they are sending to Marketo will be in JSON or XML format.
- Click "Create".
Creating a webhook
If the 3rd party documentation says that you need to specify a custom header for your Marketo webhook then once you have created the webhook follow these steps:
- Click on the "Webhook Actions" dropdown arrow.
- Click on "Set Custom Header".
- Click on the "Add" button.
- Put in the name of the header parameter.
- Put in the value of the header parameter.
- Repeat steps 3-5 for each header parameter that you need to add.
- Click "Save".
Creating a custom header
Using Tokens in Webhooks
As mentioned in the "Marketo Webhook Configuration" section previously, the content of the "Payload Template" field will depend on what information you are sending to the 3rd Party. Most likely you will want to send information about a person who triggered the webhook to be sent.
N.B. If you are looking for a general introduction to Marketo tokens and how they can save you time when building your emails, webhooks, and smart campaigns then check out the Great Use Cases for Tokens post.
Lead tokens for a form fill in payload
You can even use lead tokens within the "URL" field of the Marketo webhook to dynamically change the destination URL for each person.
Lead token in URL
Sometimes you might want to send context about the event that triggered the smart campaign sending the webhook. The Trigger Tokens Example Usage post shows you how you can use trigger tokens within the "Payload Template" to provide information about a form fill event that triggered a campaign to run.
Trigger tokens in payload
Other times you can get downright crafty and use smart campaign description tokens to populate your webhook payloads. For example, you can use the {{campaign.description}} token within the webhook payload to send a different SMS message from each smart campaign. This way you only need one webhook to send many different messages versus having to set up a webhook for each SMS message/smart campaign.
Campaign description used as SMS body
The Lead Routing to Salesforce with Chili Piper post gives another example of how you can send people through different Chili Piper routers using the {{campaign.description}} token, where each smart campaign requesting this webhook has a different router name in its description. Once again this saves you having to build multiple webhooks for each Chili Piper router/smart campaign.
Campaign description used to determine Chili Piper router
Storing Values Returned From a Webhook
When you are making a "GET" request to a 3rd party using a Marketo webhook then you might be interested in storing some of the information returned in fields on the person who triggered that webhook e.g. an enrichment platform like Clearbit or Crunchbase sends back information on an email address that you queried in their database.
Mapping response attributes to fields
One precautionary measure that I would recommend is using temporary fields to store the response variables and then only overwriting the desired fields if the temporary fields come back from the webhook populated. The reason for this is that sometimes the webhook can return a successful 200 response code but there could be an issue with the response field (see image below) so you do not want to overwrite populated fields with empty or bad values.
If something like this ever does happen and you need to revert fields that were incorrectly changed back to their original values across a bunch of leads then you can check out the Bulk API Quick Start Guide to see how you can do this.
Empty webhook response
Only overwrite desired fields if temporary fields are populated
Ideally, these temporary fields would not be used by any other webhooks or smart campaigns so that there is nothing else setting their value. You can check what other webhooks or smart campaigns might be using these fields by going to Admin > Field Management and clicking each field in turn to see the "Field Used By" list.
Field Calculations with Webhooks
I'm sure like every Marketo user who has seen Salesforce formula fields you wish that you could do some math and calculations with field values and then store the result. While Marketo does not offer this capability out of the box you can use webhooks and the free Hoosh Marketing excel calculator for webhooks.
Once you sign up for the Hoosh Marketing service you will be given a username and password that you need to append to the excel calculator endpoint. Now here comes the magical part: any excel formulas you enter in the Payload Template will be evaluated and the answer returned in the webhook response. By using lead tokens within these excel formulas we can then perform calculations with these fields and map the webhook response to another field to store the answer.
Here are two simple calculations that you can do with lead tokens:
- Converting a text value to a number: =VALUE({{lead.Behavior Score}})
- Adding two fields together: ={{lead.Firmo Score}} + {{lead.Demo Score}}
Using Hoosh to do Excel calculations
Note how the "Request Type" for this webhook is "POST" even though we are retrieving information from Hoosh and that "Request Token Encoding" should be set equal to "Form/URL".
As I mention in the "Storing Values Returned From a Marketo Webhook" section above, I recommend mapping the "result" of the webhook response to a temporary field and then only updating the desired field if the temporary field is populated.
Storing the result from Hoosh in a field
Basically, whatever formula you can make with Excel you can put into the Payload Template. Note that while Google Sheets and Excel might share a lot of the same formulas, the exact same calculation evaluated in Google Sheets and Excel can sometimes yield different results. Therefore I always recommend testing the formula in Excel or an online Excel calculator instead of Google Sheets.
It is also worth mentioning Flowboost here. Flowboost is a free tool (up to 100k webhook calls per month) that you can send JavaScript code to for evaluation using Marketo webhooks. Just like with the Hoosh tool, when we use lead tokens within the JavaScript code in the Payload Template we can perform any sort of calculation we want on field values and store the result in another field.
Flowboost Javascript webhook
Testing & Debugging Marketo Webhooks
Testing and debugging webhooks in Marketo is not the most straightforward thing in the world, especially when you just get vague messages about invalid payloads.
Webhook Lag/Webhooks Not Updating
I have noticed when testing webhooks that when I make a change to the payload template and retrigger a smart campaign to send the webhook, the webhook still sends the old payload and not the new one.
I have complained to Marketo about this but unfortunately all we can do for now is an inelegant "turn it off and then turn it back on" approach. This is much more easily understood by watching the YouTube video above but here are the steps I would take if a webhook is still sending an old payload:
- Clone the webhook you are testing
- Go to the smart campaign flow that is sending the webhook you want to test
- Replace the original webhook with the cloned webhook
- Retrigger the smart campaign, which should send the cloned webhook with the new payload
At this point, if you are finished testing then you can leave the cloned webhook in your smart campaign and delete the original webhook. However, if you want to keep testing I recommend keeping both and swapping them into the flow for testing. For example:
- An update to the payload of the cloned webhook is not taking affect i.e. Marketo is still sending the old payload
- Make the update to the original webhook and swap the original webhook into the flow for testing
- Another update to the payload of the original webhook is not taking affect
- Make this update to the cloned webhook and swap the cloned webhook into the flow for testing
- Rinse and repeat until you have finished testing
Debugging Invalid Webhook Payloads
To debug why webhook payloads are being marked as invalid I recommend setting up 2 smart campaigns:
- One campaign to listen for successful webhook sends
- One campaign to listen for failed webhook sends
Triggering for a successful webhook send
Triggering for a failed webhook send
N.B. You can also use the "Error Type" constraint on the "Webhook is Called" trigger
Then the flow of the smart campaigns will send the payload of the webhook in an email alert to your inbox with either a "Successful Webhook Send" or "Unsuccessful Webhook Send" subject line. I recommend setting up a filter in your inbox to move the successful webhook emails and failed webhook emails to seperate folders, which a) saves your inbox from becoming a mess and b) makes it easier to differentiate them.
Sending the successful webhook email
Sending the failed webhook email
Alert with successful subject line
Alert with failed subject line
Now in your inbox, it is easy to find the payloads that were successful and those that were not. To make comparison easier you can copy the successful and failed payloads into adjacent columns in a Google Sheet to see what the difference between them is.
If you want to compile a list of people who have had failed webhook sends, incase any cleanup or resending needs to be done, then you can create a smart list using the "Webhook is Called" filter and optionally filter on specific error types.
Filtering for successful webhook responses
Filtering for failed webhook responses
Filtering for specific webhook errors
Other Tools for Debugging Marketo Webhooks
For the failed payloads you can copy these into Postman and send the request from Postman to see if the issue is with the way Marketo is sending the payload or an issue with the payload itself. If you want an introduction to Postman then check out the API Quick Start Guide where I walk you through how to get set up in Postman and make your first request.
Also if you know the payload template needs to be in a certain format like JSON you can copy the payloads into online validators e.g. jsonlint, that will check the payload and if it is a good validator it will also tell you where your payload breaks standard.
Sending webhook payload using Postman
How to Call a Webhook From a Batch Campaign
Now normally, you cannot send webhooks from a batch campaign but there is a simple hack you can use to achieve this. The first step is to create a smart campaign with the "Campaign is Requested" trigger and the webhook you want to send in the flow.
Campaign is requested trigger
Sending webhook within flow of requestable campaign
Then in the flow of your batch campaign you can call the request campaign to send the webhook.
Requesting the campaign to send webhook
What Can You Unleash With Webhooks?
Now that you know the ins and outs of Marketo webhooks take a look at the use cases below to see how they can be used to do all sorts of different tasks:
- Sending messages to Slack from Marketo
- Triggering a workflow to run in Zapier
- Sending SMS messages to your customers
- Routing leads within Salesforce
- Enriching leads with information from phone number lookups
- Enriching leads with Clearbit information
Although you might not have realized it, by using webhooks you are actually making API requests to these 3rd party systems. If you want to learn more about API requests and how you can use Marketo's own API to facilitate automation and streamline workflows then check out the API Quick Start Guide.
.png)