Webhooks for program builder

Unlock the ability to integrate with almost any RESTful API with program webhooks.

Laura Russell avatar
Written by Laura Russell
Updated over a week ago

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.

1. Create the webhook

You first need to create the webhook in the Connect area of Dotdigital.

  1. Go to Connect > Webhooks.

  2. Select NEW WEBHOOK.

  3. Enter a Webhook name, for example, to describe the webhook’s purpose, and for Platform select from:

    • Create new
      Enter a new platform name into the field.

    • Choose from 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.

  4. If you are 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.

  5. 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.

  6. Expand the Authentication section, then expand the Authentication type drop-down menu and select from:

    • 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.

  7. 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.

  8. Select SAVE.

2. Configure your webhook

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.

Using webhook nodes, you can provide the specific data required for each webhook.

The Webhook program 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 continue with the process outlined below, from step 4.

If your account does not have the Webhooks permission enabled, when you drag the node onto the program canvas, you see a side panel with information about the feature.

To configure your webhook program node:

  1. 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.

  2. From the Webhooks section of the left side panel, drag the webhook node you want to use onto the canvas.

  3. Select the node and the Webhook details side panel opens.

  4. Optionally, you can expand the Webhook drop-down menu and select a different platform to use for this action.

  5. 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@.

  6. Expand the Method drop-down menu and select the appropriate method of the HTTP request made.

  7. Expand the Content-type drop-down menu and select the content type of the request.

  8. Optionally, you can use the Node text field to enter a description to display on the node inside the program builder.

  9. Expand the Headers and body data section, and enter key-value pairs for any headers to include.
    Global headers to be included in all requests can be added to the webhook profile.

  10. 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.

  11. 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.

  12. When you’re happy with your configuration, select APPLY.

Data requirements

It's always your responsibility to ensure you're supplying good, executable data, or your webhook could fail.

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.

Did this answer your question?