Webhooks can be used in programs to extend the functionality of our automations and allow you to make HTTP requests to endpoints of your choosing.
We also utilise webhooks as part of our Communications API to forward you messaging events in real-time to a web page of your choosing.
Learn more in our Developer Hub.
Before you start
Things you need to know:
The functionality within Dotdigital allows you to create a connection with another platform or application using webhooks. We do not provide or troubleshoot the specific code for any requests you want to make. You, or your developers, must provide and test this code.
Create a new webhook
You first need to create a webhook in the Connect area of Dotdigital.
Once you have created at least one webhook, you can access their program nodes in the program builder. A node is added to the program builder for each webhook you add.
Go to Connect > Webhooks.
Select NEW WEBHOOK.
1. Create webhook
In the side panel that opens:
Select CREATE WEBHOOK.
Enter a Webhook name, for example, to describe the webhook’s purpose.
For Platform choose from:
Create new
Enter a new platform name into the field.Choose an existing
Expand the drop-down menu and select from an existing platform.
This is either a platform you have previously added yourself, or one which has been enabled for you by Dotdigital. Learn more in Enable a program webhook.
If you’re creating a new platform, enter the Base URL for the webhook to use.
If you selected an existing platform, the Base URL pre-populates for you.Optionally, select the Limit request rate switch to limit the rate that requests are made by the profile.
Some providers won't allow too many requests to be sent at once by the same profile.
If you set this to Yes, enter the maximum number of requests per minute you want to set.
Expand the Authentication section, then expand the Authentication type drop-down menu and choose from:
None
Proceed without requiring any of the below authentication types.Basic
Enter the Username and Password to use for authentication.API Key
Enter the Key and Value, then expand the Add to drop-down menu and select whether the Key should be added to the Header or Query Params of the request.Bearer token
Enter the token.
Authentication values entered here are automatically passed in the webhook call. If you want to pass any additional custom values, you can do this in the Global headers section.
Optionally, expand the Global headers section and add key-value pairs for any global headers that must always be included with the webhook.
Headers you enter here automatically populate in the Headers section of the webhook program node.Select SAVE.
2. Configure your webhook
You don’t have to configure your webhook at this point. You can choose to do this at a later time through the webhook program node when building an automation.
If you do configure the webhook now, it becomes available as a template that you can use across your automated programs. Webhooks configured inside a program node are for use in that program node only.
If you don’t want to configure now, select APPLY.
Learn more in the section Webhook program nodes.
Creating the webhook as a template means that you don’t have to manually enter the details for the webhook request each time you want to use it in a program. You can just drag the Webhook node onto the program canvas, and use the templated configuration.
You can make changes to a templated Webhook node within a program, and this does not change the template itself.
To create a webhook template, in the side panel:
Select CONFIGURE WEBHOOK.
For Endpoint, the base URL you added to the selected platform is populated automatically. In the text field, supply any additions to the URL, for example, paths like
/contact.
To add personalisation, select the personalisation icon on the far right, allowing for/contact/@EMAIL@, or, alternatively, URL parameters such as/contact.php?email=@EMAIL@.
Expand the Method drop-down menu and select the appropriate method of the HTTP request made.
Expand the Content-type drop-down menu and select the content type of the request.
Optionally, you can use the Node text field to enter a description to display on the node inside the program builder.
Expand the Headers and body data section, and enter key-value pairs for any headers to include.
Any global headers you added when creating the webhook are automatically populated.In the Body data field, add the relevant information to complete the request. Select the person icon in the bottom left of the field to add data field personalisation markers.
To test the webhook, select FIND CONTACT and then search for and select a contact to test to. The contact must exist in your Test list.
Select SUBMIT to make the test request. A response is provided in the side panel.
When you’re happy with your configuration, select APPLY, then APPLY again.
Data requirements
It's always your responsibility to ensure you're supplying good, executable data, or your webhook could fail.
Webhook program nodes
Default webhook node
When you create or edit a program, you see a generic Webhook node under the Webhooks section of the left side menu in the program builder.
If your account has the Webhooks permission enabled, adding this node to your program allows you to create and configure a webhook directly in the program builder.
To do this, drag in and place the node, then select it to open the side panel. Select CREATE WEBHOOK, then follow the steps in section 1 of this article, from step 3.
Then, select CONFIGURE WEBHOOK and follow the steps in section 2 of this article.
If your account doesn’t have the Webhooks permission enabled, when you drag the node onto the program canvas, you see a side panel with information about the feature.
Custom webhooks
Any webhooks that you have created are also displayed in the side panel. You see a node for each webhook platform (or provider) that you have added.
To add a webhook you have created to your program:
Go to Automation > Programs, and create a new program, or edit an existing one.
Learn more in the Program builder section of the Help Centre.From the Webhooks section of the left side panel, drag the webhook node for the platform you want to use onto the canvas.
Select the node and the Webhook details side panel opens.
Expand the Webhook drop-down menu and select the webhook you want to use.
If the node you have added to your program was created as a template, meaning the configuration was completed when the webhook was created, then the Details and Headers and body data sections have their data pre-populated for you. You can make edits to any of the information if you want to.
If the webhook you chose was not created as a template, you can follow the steps in the section Configure your webhook to add the details needed for the request.
When you’re happy with your configuration, select APPLY.
Once a program is activated and a contact reaches the webhook node in your program, the body data you entered is personalised with the contact's information and sent to the endpoint specified. The endpoint should then respond with an appropriate response code.