Versions Compared

Old Version 1

changes.mady.by.user Massimo Arrigoni

Saved on

compared with

New Version Current

changes.mady.by.user tutti_support

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Webhooks allow you to communicate to another application that something happened in your MailUp account. It's a tool that programmers use to receive real-time information that allows for deep integration between applications. For example, MailUp could let a CRM system know that somebody unsubscribed.

Calls to URLs when even happens are nothing new in the programming world. What's special about a webhook is that webhooks are"

  • Customizable: you can tell MailUp when to make that call, to which URL, and what parameters to include in the call
  • Smart: if the receiving server does not respond successfully, MailUp will try again (it retries 5 times, every 5 minutes for a total of 25 minutes)
  • Standardized: the way information is provided to the receiving end (the "Callback URL") follows certain standards that make it predictable. The Web page that receives the call (the "Callback URL") can be programmed in any programming language.

...

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.

Image Added

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

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.