Configuring a webhook

To add a new webhook, select Settings > Account Settings > Developer's Corner > Webhooks and click on Add new webhook.

As mentioned in our brief overview of webhooks, they're highly customizable. That's why, when you create or edit a webhook, there are several settings that you can configure. Let's review them one by one.

Name: enter a descriptive name for the webhook (for internal purposes only)
Callback URL: the URL of the page that will receive the "call" when the webhook is triggered
Event: The type of webhook: there are currently 4 events that can trigger the execution of a webhook:
- Subscribe: a recipient subscribed to the List
- Unsubscribe: a recipient unsubscribed from the List
- Changeprofile: a recipient's profile was updated. A modification in the groups that a recipient is assigned to counts as a profile change.
- Delete: a recipient was removed from the List
Source: the event can originate from three different sources:
- API: the event occurred due to an API call. For example, a recipient was registered in MailUp from a form that executed an API call to MailUp
- Console: the event occurred due to some operation being executed in the admin console. For example, a new recipient was added manually as a subscriber in the admin console.
- Recipient: the event occurred due to an action that a recipient took. For example, a recipient unsubscribed.
Method: the method in which the callback is technically executed. It can be a POST or a GET.
Active: whether the webhook is active or inactive.
Encrypted: whether the callback is encrypted. If so, you will need to specify a key.
- MailUp will encrypt the data using RC4 encryption and the key provided
- The data is then converted to Base64 encoding.
- The receiving page - knowing the key - can perform the opposite operations to extract the data.
Parameters: the parameters sent in the callback. See below for details.

Parameters

The parameters that can be included in the callback are:

[EventDate]: the date in which the event occurred, in ISO 8601 format (e.g.: 2012-09-12T11:18:37.664+02)
[IdConsole]: the account ID
[IdList]: the list ID
[IdNL]: the message ID
[EventType]: the type of event
[EventSource]: the source of the event
[Reason]: the reason why a recipient unsubscribed. It only applies to the unsubscribe event type and includes the code that defines the different unsubscribe types.
[Email]: the recipient's email
[Prefix]: the recipient's mobile phone international prefix
[Number]: the recipient's mobile phone
[Groups]: a comma-separated array of the groups that the recipient belongs to in the List [IdList]
[Channel]: takes the values:

- Unknown = -1
- Mail = 0
- Sms = 1
- Fax = 2
- Social = 5

Plus all of the recipient fields that are in use for that MailUp account

See a sample callback.

Limitations to webhooks

Currently, webhooks are not executed:

When there is a bulk import
When a Web service is used (this is meant for Rest Api calls, while it is activated through interaction with Http Api calls)

In addition, please note that webhooks are List-specific, and you cannot currently create a webhook that applies to multiple lists. In the future, you will be able to quickly copy a webhook to create a similar or identical one in a new List.

Related articles