Skip to main content

How do I send data from MailBlue to an external app using a webhook?

This article explains how to set up webhooks in MailBlue, which data you can send and how to test them.

Written by Yoeri van MailBlue
Feature available from the Starter subscription

​

​

What is a webhook?

A webhook is an automated message sent from one system to another when an event occurs. In MailBlue, you can send data to an external database or app, for example when a contact is updated, a deal task is created, or someone clicks a link in an email. This lets you update contact, campaign, deal and custom object activity in the receiving app.

​

Webhooks are useful when the external software has no direct integration with MailBlue. For example, you can send data when an account is added or a contact record changes.

​

Important: The receiving app must have an API and accept HTTPS POST requests on the standard HTTPS port (443). You cannot connect incoming webhooks directly to MailBlue.

​

​

How can I use webhooks?

You can set up webhooks in two ways in MailBlue. The method you choose determines when the request is sent and what you can configure.

  • In an automation: available from the Plus plan. The 'Webhook' action sends data when a contact reaches that step. You do not need to create a webhook under 'Settings' first.

  • In settings: available from the Starter plan. A webhook under 'Settings' > 'Developer' responds to selected events, such as a contact being updated or a campaign being opened. You can also select what initiates the event.

​

The new 'Webhook' automation action settings do not change existing webhooks under 'Settings' > 'Developer'.

​

​

Which webhook types can I use in settings?

Under 'Settings' > 'Developer', you can create webhooks for standard objects and custom objects. Available object types and events depend on your plan. Some accounts have both types; others only have standard webhooks.

​

Standard object webhooks send data for events involving contacts, deals, accounts, campaigns and websites. The available standard objects depend on your plan.

​

Custom object webhooks send data when an event occurs involving a custom object. These can be objects from a supported integration or objects created through the API or 'Manage Data' in your account.

​

For Shopify and WooCommerce, the following custom object events are supported when this feature is available for your account:

  • Orders: created, updated or deleted.

  • Products: created, updated or deleted.

​

Which events can I send from settings?

For webhooks configured under 'Settings', you can select various event types:

  • Account: added or updated.

  • Campaign: forwarded, opened, shared or started sending.

  • Contact: added or updated, added to, updated on or removed from an account, note added, tag added or removed, task added, or unsubscribed.

  • Deal: added or updated, note added, pipeline added, stage added, task added or completed, or task type added.

  • Email: bounced or replied to.

  • Link: clicked.

  • List: added.

​

How do I add a webhook to an automation?

The 'Webhook' action sends contact data to a URL when a contact reaches that step in your automation. You do not need to configure a separate event to trigger this webhook, as the automation handles that.

​

This is where you find the 'Webhook' action in the automation action menu:

Screenshot of the action menu with 'Webhook' highlighted under 'Workflow'.

​

  1. Click 'Automations' in the left menu and open the relevant automation with 'Edit'.

  2. If the automation is active, pause it before making changes.

  3. Click the plus sign (+) where you want to add the action.

  4. Under 'Add an action', choose 'Workflow' and then 'Webhook'.

  5. Enter the receiving app's HTTPS URL.

  6. Under 'Output type', choose 'JSON' or 'x-www-form-urlencoded'.

  7. Add authentication, custom headers or query parameters if needed.

  8. Under 'Include metadata', select the related data groups to send.

  9. Click 'Save'.

  10. Test the action with a test contact and inspect the received request in the external app. Resume the automation when everything works as expected.

​

Important: Pause an active automation before changing the webhook action. Resume it after testing so contacts can continue through the workflow.

​

​

Which output format can I choose for a webhook?

The output type controls how the request body is sent to the receiving URL. It does not control the receiving app's response.

  • 'JSON': sends a JSON object. This is the default for new webhook actions.

  • 'x-www-form-urlencoded': sends form data. Choose this if the receiving app expects that format.

To switch from form data to JSON, select 'JSON', read the warning and click 'Switch to JSON'.

​

Important: Changing the output type changes how the external app must process the request. Check that the app supports the new format first.

​

​

How do I add authentication and custom headers?

If the receiving app requires a secret in a request header, enter its 'Name' and 'Value' under 'Authentication'. For a bearer token, for example, enter Authorization as the name and Bearer YOUR_TOKEN as the value.

​

A saved authentication value is hidden when you reopen the action. Leave its value field empty to retain the saved secret, as long as the URL stays the same. If you change the URL, enter the secret again. To remove authentication, clear both the name and value and save the action.

​

The authentication value is sent exactly as the header value. This setting does not generate a signature for the request body. After importing a shared automation, enter your own authentication value.

​

Under 'Custom headers', enter additional rows using 'Header name' and 'Header value'. Click 'Add header' for another row. You can add up to ten custom headers.

​

Important: Custom header values remain visible when you reopen the action. Put secrets under 'Authentication'. Header names cannot contain spaces or use Content-Type, Content-Length, Host or Transfer-Encoding. The authentication header name must not match a custom header name.

​

​

How do I add query parameters to a webhook?

Under 'Custom query params', enter a 'Parameter' and 'Value' to add information to the receiving URL. Click 'Add query param' for another row.

​

You can use personalization tags in query parameter values. For example, enter email as the parameter and %EMAIL% as the value. MailBlue resolves the email address for each contact and URL-encodes the value.

​

Saved parameters are appended after any parameters already in the URL. A parameter is still sent when its value resolves to an empty string. You can also use personalization tags directly in the URL.

​

Account tags use account details when available. Deal tags use the deal that triggered the automation when available. Otherwise, MailBlue uses the contact's most recently created deal. This differs from the 'Deals' metadata option, which sends associated deal records.

​

Use 'Authentication' for secret values, not query parameters. Query parameters become part of the receiving URL.

​

​

Which contact details and metadata are sent?

A webhook action in an automation always sends basic contact data and the automation ID (seriesid). Basic data includes the contact ID, email address, first name, last name, phone number and account name fields. When available, the IPv4 address (ip4) is included too.

​

Under 'Include metadata', you can choose which extra groups to send:

  • 'Custom fields': the contact's custom field values.

  • 'Lists': list IDs, list names and contact subscription statuses.

  • 'Tags': the contact's tag names.

  • 'Accounts': associated account IDs and names.

  • 'Deals': associated deals with IDs, titles, values, currencies, statuses and stages.

  • 'Custom objects': related custom object records accessible to your account.

For new webhook actions, 'Custom fields' is selected by default. All other metadata groups are off by default. Each option includes a whole group; there is no free-form request body editor.

​

​

What does a webhook request body look like?

With 'JSON', basic contact data is under contact and the automation ID is under seriesid. Selected data groups appear alongside them as custom_fields, lists, tags, accounts, deals and custom_objects.

​

Here is a shortened JSON example with 'Custom fields' and 'Tags' selected:

{   "contact": {     "id": "123",     "email": "[email protected]",     "first_name": "Alex",     "last_name": "Morgan",     "phone": "",     "orgname": "Example Co",     "customer_acct_name": "Example Co"   },   "seriesid": "456",   "custom_fields": {     "preferred_color": "Blue",     "job_title": null   },   "tags": ["Customer"] }

​

Your values and IDs may differ. Custom field keys use lowercase personalization tag names. Unselected groups are omitted. Selected groups without records are empty arrays ([]), while an empty custom-fields map is an empty object ({}). Empty custom field strings become null in JSON.

​

Each custom object record contains id, schema_id and fields. If MailBlue cannot load the data, custom_objects is omitted from the request. An omitted key does not necessarily mean there are no records.

​

With 'x-www-form-urlencoded', the layout differs: custom fields remain under contact[fields]; tags are sent as a comma-separated value under contact[tags]; and selected lists, accounts, deals and custom objects are top-level groups. Empty groups are omitted from form data.

​

​

How do I update an existing webhook action?

Older URL-only webhook actions keep their existing form body and contact data until you edit and save them. When you open one, 'x-www-form-urlencoded' is selected and the metadata groups are unchecked.

​

Important: Before saving an older action, check the groups under 'Include metadata'. Even if you keep form encoding, some fields from the previous payload may be missing after saving. Test the webhook after any format or data selection change.

​

If you only see the URL field, the configurable options are not enabled for your account. You can continue using the URL-only action.

​

​

How do I create a webhook in settings?

With standard webhooks in 'Settings', you can send data to an external app from the Starter plan when a selected event occurs. This method is separate from the 'Webhook' automation action.

​

You can find them under 'Settings' > 'Developer' > 'Manage webhooks'. This is where you manage webhooks:

Screenshot of the 'Developer' settings page with 'Manage webhooks' highlighted.

​

How do you set up a standard object webhook?

  1. Click the gear icon and open 'Settings'.

  2. Click 'Developer' in the left menu.

  3. Click 'Manage webhooks' and then 'Add'.

  4. Choose the type of webhook you want to create.

  5. Enter a name and the receiving app's address in 'URL'.

  6. Under 'Type', select the event or events that trigger the webhook. You can select more than one.

  7. Select what initiates the event, for example a contact, an account user, a system process or an API call.

  8. If needed, select the list associated with the webhook. This field appears only when the selected webhook type requires a list.

  9. Click 'Save'.

​

How do you set up an app or custom webhook? Follow the same initial steps via 'Settings' > 'Developer' > 'Manage webhooks' > 'Add'. Then enter the following details:

  1. Enter a name for the webhook.

  2. Under 'Type', select the event or events that trigger it.

  3. Enter the receiving URL under 'URL'.

  4. Click 'Save'.

​

How do you set up an ecommerce custom object webhook? After selecting this type, enter the following details:

  1. Enter a name for the webhook.

  2. Enter the receiving address under 'URL'.

  3. Under 'Events', select one or more events that trigger the webhook.

  4. Click 'Save'.

​

What can initiate a webhook from settings?

When you create a webhook under 'Settings' > 'Developer', you choose what initiates it. The options are:

  • By a contact: when a contact causes an event, such as opening a campaign.

  • By a user: when an account administrator performs an action, such as adding a contact.

  • By system processes: when an automated system performs the action, for example when an email bounces.

  • By the API: when an API call causes the action, for example when a contact is added using the contact_add call.

​

How do I test whether a webhook works?

Webhook in settings: go to 'Settings' > 'Developer' > 'Webhooks' and click 'Send sample data'. MailBlue sends test data to the URL configured for that webhook.

​

Webhook in an automation: use a test contact that reaches the 'Webhook' action. Then check the receiving app for the HTTPS POST request, its output format and included data. Resume the automation afterward if needed.

​

​

How are webhook data received?

MailBlue sends webhook data as an HTTPS POST request to the receiving URL. Settings-level webhooks send data as POST parameters. For the automation action, the request body structure depends on the selected output type: JSON or form data.

​

For webhooks configured under Developer Settings, MailBlue guarantees delivery at least once. This means the same event can sometimes be delivered more than once.

​

Account for duplicate deliveries in the receiving app so one event is not unintentionally processed multiple times.

​

​

How can I secure settings-level webhooks with headers?

For platform webhooks configured under Developer Settings, you can add custom request headers through the webhook API when creating or editing a webhook. These API settings are separate from the 'Webhook' action in an automation.

​

Each API header has a name, a value and is_signature. There are two types:

  • Standard header: sends the value exactly as entered, for example for authentication or integration metadata.

  • Signature header: when is_signature is set to true, MailBlue uses the provided value as a secret to generate an HMAC-SHA256 signature from the webhook request body. The generated signature is sent as the header value. You can configure up to one signature header.

​

The receiving service can use the signature header to verify the request's origin and that the body has not changed in transit. The 'Authentication' field in an automation webhook only sends the supplied header value and does not generate an HMAC signature.

​

​

Which characters and limits apply to webhooks?

Webhook URLs can contain letters and numbers plus the following special characters: $-_.+!*' (),.

​

According to the existing MailBlue documentation, there is no character limit for a note or other field included in a webhook.

​

​

What can I do if a webhook does not work?

Check the receiving HTTPS URL, whether the app accepts POST requests on port 443, the output format it expects, and the authentication and headers. Then test the webhook again.

​

MailBlue Support can offer general advice on setting up a webhook, but cannot troubleshoot the receiving app's processing on your behalf. If needed, consult a technical specialist.

​

​

Frequently asked questions

Can I use webhooks on the Starter plan?

Yes. Settings-level webhooks under 'Settings' > 'Developer' are available from Starter. The 'Webhook' automation action requires at least Plus.

Can I choose exactly which fields an automation webhook sends?

You can switch whole groups on or off under 'Include metadata'. You cannot freely edit the request body or choose individual fields within a group.

What is the default format for a new webhook action?

New webhook actions default to 'JSON' with 'Custom fields' included. Other metadata groups are disabled by default.

What happens when I save an existing webhook action?

After saving an older URL-only action, some fields from the previous request may be missing. Review the metadata selections and test the action again.

Can MailBlue receive an incoming webhook directly?

No. You cannot connect incoming webhooks directly to MailBlue. The webhooks described here send data from MailBlue to an external URL.

Why might I receive the same settings-level webhook more than once?

MailBlue guarantees at-least-once delivery for platform webhooks configured under Developer Settings, so one event may result in multiple requests.

Can I also use custom object webhooks?

It depends on your plan. Supported custom objects can come from connected apps or objects created through the API or 'Manage Data'.

How does a signature header differ from automation authentication?

For a platform webhook, the API can generate an HMAC-SHA256 signature using is_signature. For an automation webhook, the authentication value is only sent directly as a header.

Did this answer your question?