Spotler MailPro supports webhooks, which allow you to receive real-time notifications when specific events occur in your email campaigns or contact data. This enables seamless integration with external systems to automate workflows, track user activity, or synchronize databases.
In this article, you'll find details about:
Webhooks glossary
| Term | Definition |
|---|---|
| Subscriber | Entity subscribing to a topic and providing a delivery URL to receive events. |
| Vendor | The owner of a subscription on a specific webhook topic. |
| Topic | System event to which a subscriber can listen. |
| Delivery URL | The HTTPS endpoint where event notifications are delivered. |
Managing webhooks via REST API
Currently, webhooks in Spotler MailPro can only be managed via the REST API. More technical information on usage of the REST API can be found in the Swagger documentation.
Webhook request headers
| Header | Description | Example |
|---|---|---|
| x-mailpro-license | The name of the mailpro license that initiated the webhook request. It’s the value part of the license domain e.g. https://sandbox.webpower.eu/ | sandbox |
| x-mailpro-subscriber-id | The identifier of the subscriber in which the webhook is configured. | 5 |
| x-mailpro-topic | Name of the topic which defines the payload of the request. | contact.created |
| x-mailpro-signature | sha256 hmac hash of the body signed with the secret configured in the subscriber. | 2c8508...92c31e91 |
Available webhook topics
The following topics are supported:
Gets triggered after the creation of an contact.
Note
This topic don’t honors the opt-in state of the contact. Which can result in receiving contacts that don’t (yet) have finished their opt-in process for receiving (marketing) emails.
| Field | Datatype | Example |
|---|---|---|
| contact_id | int | 1 |
| campaign_id | int | 25 |
| string | user@example.com | |
| mobile_nr | string|null | +31612345678 |
| lang | string|null | null |
| fields | {field: string, value: string}[] | [{field: "firstName", value: "John"}, {field: "lastName", value: "Doe"}] |
| created_on | string (ISO_8601) | 2024-09-13T12:30:00+02:00 |
{
"contact_id": 300012,
"campaign_id": 20,
"email": "user@example.com",
"mobile_nr": null,
"lang": null,
"fields": [
{ "field": "firstname", "value": "John" },
{ "field": "lastname", "value": "Doe" }
],
"created_on": "2024-09-13T12:30:00+02:00"
}
Get’s triggered after the creation of an contact.
| Field | Datatype | Example |
|---|---|---|
| contact_id | int | 1 |
| campaign_id | int | 25 |
| string | user@example.com | |
| mobile_nr | string|null | +31612345678 |
| lang | string|null | null |
| fields | {field: string, value: string}[] | [{field: "firstName", value: "John"}, {field: "lastName", value: "Doe"}] |
| changed_on | string (ISO_8601) | 2024-09-13T12:30:00+02:00 |
{
"contact_id": 300012,
"campaign_id": 20,
"email": "user@example.com",
"mobile_nr": null,
"lang": null,
"fields": [
{ "field": "firstname", "value": "John" },
{ "field": "lastname", "value": "Doe" }
],
"changed_on": "2024-09-13T12:30:00+02:00"
}
Get’s triggered after the removal of a single contact.
| Field | Datatype | Example |
|---|---|---|
| contact_id | int | 1 |
| campaign_id | int | 25 |
| string | user@example.com | |
| mobile_nr | string|null | +31612345678 |
| lang | string|null | null |
| fields | {field: string, value: string}[] | [{field: "firstName", value: "John"}, {field: "lastName", value: "Doe"}] |
| removed_on | string (ISO_8601) | 2024-09-13T12:30:00+02:00 |
{
"contact_id": 300012,
"campaign_id": 20,
"email": "user@example.com",
"mobile_nr": null,
"lang": null,
"fields": [
{ "field": "firstname", "value": "John" },
{ "field": "lastname", "value": "Doe" }
],
"removed_on": "2024-09-13T12:30:00+02:00"
}
Get’s triggered after a contact got added to a group.
| Field | Datatype | Example |
|---|---|---|
| contact_id | int | 1 |
| campaign_id | int | 25 |
| group_id | int | 70 |
| added_on | string (ISO_8601) | 2024-09-13T12:30:00+02:00 |
{
"contact_id": 300012,
"campaign_id": 20,
"group_id": 70,
"added_on": "2024-09-13T12:30:00+02:00"
}
Get’s triggered a contact got removed from a group.
| Field | Datatype | Example |
|---|---|---|
| contact_id | int | 1 |
| campaign_id | int | 25 |
| group_id | int | 70 |
| removed_on | string (ISO_8601) | 2024-09-13T12:30:00+02:00 |
{
"contact_id": 300012,
"campaign_id": 20,
"group_id": 70,
"removed_on": "2024-09-13T12:30:00+02:00"
}
Receives any message of topic that starts with contact.
Payload definition: One of the contact.definitions based on the received topic given as HTTP header.
Note
This topic will always receive newly added contact topics in future product releases. Make sure to always check the topic type in the header before processing the content, as we can’t guarantee the payload definition of new topics are inline with the existing one's.
Get’s triggered after contact clicked on a link inside a mail.
| Field | Datatype | Example |
|---|---|---|
| contact_id | int | 1 |
| campaign_id | int | 25 |
| mailing_id | int | 200 |
| sendout_id | int|null | 312 |
| click_name | string | Request now your today |
| url | string | https://spotler.com/demo |
| reference | string|null | automation_338 |
| clicked_on | string (ISO_8601) | 2024-09-13T12:30:00+02:00 |
{
"contact_id": 300010,
"campaign_id": 20,
"mailing_id": 132,
"sendout_id": 52,
"click_name": "Request now your today",
"url": "https://spotler.com/demo",
"reference": "automation_338",
"clicked_on": "2024-09-13T12:30:00+02:00"
}
Get’s triggered after contact opened a received mail.
| Field | Datatype | Example |
|---|---|---|
| contact_id | int | 1 |
| campaign_id | int | 25 |
| mailing_id | int | 200 |
| sendout_id | int|null | 312 |
| reference | string|null | automation_338 |
| opened_on | string (ISO_8601) | 2024-09-13T12:30:00+02:00 |
{
"contact_id": 300010,
"campaign_id": 20,
"mailing_id": 132,
"sendout_id": 52,
"reference": "automation_338",
"opened_on": "2024-09-13T12:30:00+02:00"
}
Get’s triggered after a sms got sent to a contact.
| Field | Datatype | Example |
|---|---|---|
| contact_id | int | 1 |
| campaign_id | int | 25 |
| sms_id | int | 300 |
| sendout_id | int|null | 105 |
| reference | string|null | automation_338 |
| sent_on | string (ISO_8601) | 2024-09-13T12:30:00+02:00 |
{
"contact_id": 300010,
"campaign_id": 20,
"sms_id": 132,
"sendout_id": 52,
"reference": "automation_338",
"sent_on": "2024-09-13T12:30:00+02:00"
}
Get’s triggered after the creation of an contact.
| Field | Datatype | Example |
|---|---|---|
| contact_id | int | 1 |
| campaign_id | int | 25 |
| email_id | int | 301 |
| sendout_id | int|null | 105 |
| weblink | string | https://local.domain.com/x/?midrid |
| reference | string|null | automation_338 |
| sent_on | string (ISO_8601) | 2024-09-13T12:30:00+02:00 |
{
"contact_id": 300010,
"campaign_id": 20,
"email_id": 132,
"sendout_id": 52,
"weblink": "https://local.domain.com/x/?midrid",
"reference": "automation_338",
"sent_on": "2024-09-13T12:30:00+02:00"
}
Get’s triggered after the mail server of the contact denied delivering the sent mail.
Note
Only bounce messages of the contact mail servers are reported. This topic will not be triggered when the contact is included in any of the bounce exclude lists. Those instances will be handled as a not sent interaction.
| Field | Datatype | Example |
|---|---|---|
| contact_id | int | 1 |
| campaign_id | int | 25 |
| email_id | int | 301 |
| sendout_id | int|null | 25 |
| bounce_type | "soft"|"hard" | "soft" |
| bounced_on | string (ISO_8601) | 2024-09-13T12:30:00+02:00 |
| reference | string|null | automation_338 |
{
"contact_id": 300010,
"campaign_id": 20,
"email_id": 132,
"sendout_id": 52,
"bounce_type": "soft",
"bounced_on": "2024-09-13T12:30:00+02:00",
"reference": "automation_338"
}
Get’s triggered after the contact filed a spam complaint.
| Field | Datatype | Example |
|---|---|---|
| contact_id | int | 1 |
| campaign_id | int | 25 |
| mailing_id | int | 301 |
| sendout_id | int|null | 25 |
| complained_on | string (ISO_8601) | 2024-09-13T12:30:00+02:00 |
{
"contact_id": 300010,
"campaign_id": 20,
"mailing_id": 132,
"sendout_id": 52,
"complained_on": "2024-09-13T12:30:00+02:00"
}
Get’s triggered after the a contact unsubscribed.
| Field | Datatype | Example |
|---|---|---|
| contact_id | int | 1 |
| campaign_id | int | 25 |
| mailing_id | int | 301 |
| sendout_id | int|null | 25 |
| string | user@example.com | |
| mobile_nr | string|null | +31612345678 |
| lang | string|null | null |
| fields | {field: string, value: string}[] | [{field: "firstName", value: "John"}, {field: "lastName", value: "Doe"}] |
| unsubscribed_on | string (ISO_8601) | 2024-09-13T12:30:00+02:00 |
{
"contact_id": 300012,
"campaign_id": 20,
"mailing_id": 132,
"sendout_id": 52,
"email": "user@example.com",
"mobile_nr": null,
"lang": null,
"fields": [
{ "field": "firstname", "value": "John" },
{ "field": "lastname", "value": "Doe" }
],
"unsubscribed_on": "2024-09-13T12:30:00+02:00"
}
Receives any message of topic that starts with interaction.
Payload definition: One of the interaction. definitions based on the received topic given as HTTP header.
Note
This topic will always receive newly added interaction topics in future product releases. Make sure to always check the topic type in the header before processing the content, as we won’t guarantee the payload definition of new topics are inline with the existing one's.