Integratie: Webhooks

Spotler MailPro ondersteunt webhooks, waarmee je realtime meldingen kunt ontvangen wanneer specifieke gebeurtenissen plaatsvinden in je e-mailcampagnes of contactgegevens. Dit maakt een naadloze integratie met externe systemen mogelijk om workflows te automatiseren, gebruikersactiviteit te volgen of databases te synchroniseren.

In dit artikel vind je informatie over:

Woordenlijst Webhooks
Een webhook instellen
Webhook request headers
Beschikbare webhook topics

Woordenlijst Webhooks

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.

Een webhook instellen

Om webhooknotificaties te ontvangen, maak je eerst een webhooksubscription aan via de Spotler MailPro REST API.

1. Bereid je delivery URL voor

Maak in je eigen applicatie een HTTPS-endpoint dat webhookrequests kan ontvangen en verwerken.

2. Maak je webhooksubscription aan

Gebruik de Spotler MailPro REST API om een webhooksubscription aan te maken met de volgende instellingen:

Delivery URL: het HTTPS-endpoint waarop je notificaties wilt ontvangen.
Topic: kies een gebeurtenis uit de beschikbare webhook topics. Gebruik bijvoorbeeld contact.created om notificaties te ontvangen wanneer een contact wordt aangemaakt.
Secret: het secret waarmee webhookrequests worden ondertekend. Jouw applicatie gebruikt dit secret om de signature te controleren.

3. Ontvang en controleer notificaties

Zodra de subscription is aangemaakt, stuurt MailPro requests naar je delivery URL wanneer gebeurtenissen voor het ingestelde topic plaatsvinden.

Controleer de x-mailpro-signature-header met je ingestelde secret.

4. Test je koppeling

Laat een gebeurtenis voor het ingestelde topic plaatsvinden en controleer of jouw applicatie de notificatie ontvangt en verwerkt. Je endpoint moet een 2xx-antwoord teruggeven om succesvolle ontvangst te bevestigen.

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

Retry mechanisme

Wanneer een Webhook faalt (statuscode anders dan 2xx), doordat bijvoorbeeld de afleverlocatie tijdelijk te druk of niet beschikbaar is, zal er nog een poging gedaan worden om het bericht af te leveren. In totaal zullen 5 pogingen gedaan worden, met iedere keer een iets langere tussenpose. De eerste retry zal na 500 milliseconde gedaan worden, en deze timeoutperiode zal na elke poging verdubbeld worden. De laatste poging wordt dus na 8000 milliseconde gedaan. Als deze poging ook nog faalt, zal deze als mislukt worden weggeschreven in onze database.

Beschikbare webhook topics

De volgende topics worden ondersteund:

contact.created

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
email	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"
}

contact.changed

Get’s triggered after the creation of an contact.

Field	Datatype	Example
contact_id	int	1
campaign_id	int	25
email	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"
}

contact.removed

Get’s triggered after the removal of a single contact.

Field	Datatype	Example
contact_id	int	1
campaign_id	int	25
email	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"
}

contact.group.added

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"
}

contact.group.removed

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"
}

contact.any

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.

interaction.clicked

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"
}

interaction.opened

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"
}

interaction.sms.sent

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"
}

interaction.email.sent

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"
}

interaction.email.bounced

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"
}

interaction.complaint

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"
}

interaction.unsubscribed

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
email	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"
}

interaction.any

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.

Artikelen in deze sectie

Woordenlijst Webhooks

Een webhook instellen

1. Bereid je delivery URL voor

2. Maak je webhooksubscription aan

3. Ontvang en controleer notificaties

4. Test je koppeling

Webhook request headers

Retry mechanisme

Beschikbare webhook topics

Note

Note

Note

Note