In addition to the immediate, scheduled, and recurring send email options, emails can be configured to be triggered via a webhook. This way, you can send an email from Ascent360 on an event-basis and pass-in data in the webhook payload to be used in the email send. This article will walk you through setting up a webhook-triggered email send.
Why Use a Webhook to Trigger an Email?
Triggering an email from a webhook allows you to go beyond the standard email schedule options and gives you granular control over when to send the email, whom to send it to, and what to include in the message. Below are some use cases that may suit your needs for sending a webhook-triggered email through Ascent360.
- Send an email whenever an event happens in an upstream system.
- Website Update (snow reports)
- Bookings, transactions, or reservations: creation, cancellation, or updates
- Form submission (for non-Ascent360 forms)
- Send an email and dynamically replace content in the email with data in the event payload.
- Recent snowfall and upcoming forecast
- Work Order updates: Technician name, comments, and estimated completion time
- Shipping updates: Tracking ID and URL
- Booking Creation: Confirmation ID, arrival date & time, special instructions
Prepare your email with merge tags
Using a Webhook, you can add personalization to your email and pass-in data in a payload that wouldn't normally be available in the CDP. During the sending process, you'll have an opportunity to map these merge tags to your payload if needed.
Merge tags can be inserted via three methods:
- Use the text formatting toolbar within the email to click Merge Tags, then select your Field from the list and designate a default value.
- Use the text formatting toolbar within the email to click Merge Tags, then select Custom at the bottom and name your merge tag and provide a default value (if applicable).
- Manually declare a merge tag by typing the merge tag syntax. Examples below:
{{[myMergeTag]}}{{[myMergeTag|"defaultValue"]}}
Custom or manually-declared merge tags should have unique names that are not shared with other fields in your CDP. Your merge tag name should be alphanumeric and contain no spaces.
The Email Send will account for the text styling changes made in the editor, including font style, size, color, highlight, etc.
| In the Editor: | Live Send: |
|
|
Send a Webhook Triggered Email
Once your design is finalized, select Triggered Email from the Email Send dialogue.
Send To Section
In the "Send To" section, select whether this email will go to an audience or whether recipients will be provided in the webhook payload.
- Option 1 - Send to an Audience: Select a saved audience from the drop-down. Select this option if email recipients will not be provided from the system that is triggering the webhook.
- Option 2 - Custom Recipient: Provide a recipient in the webhook payload. Select this option if the email address for the recipient will be provided from the system that is triggering the webhook. This option supports 1 recipient per webhook trigger.
IMPORTANT:
- If you send to an audience, Ascent360 will evaluate email permissions before sending the email.
- If you provide the recipient in the payload, Ascent360 will not evaluate CDP email permissions before sending the email. It is your responsibility to ensure that email addresses you are providing are eligible for email communication through this method.
From Section
Select your From Name, From Address, and Reply To Address for this triggered email.
Properties Section
Configure your email properties, including your Subject, pre-header, and Tracking Parameters
Trigger Section
The Trigger section displays options to view the suggested payload format or provide a payload and mapping.
If you don't already have a predetermined payload that you plan on using, please use our suggested format. The suggested format lists the JSON keys & values that Ascent360 will expect when evaluating for recipients and merge tags. Not every key needs to have a value (See Section on Merge Tag Precedence below), but each key in your payload needs to match exactly what is shown (spelling/spacing/capitalization) on this page. Additional keys included in the payload will be ignored or may cause the trigger to fail.
The payload keys/values only apply to merge tags within the email body itself; changing email properties (subject, from name, from email address) via the payload is not supported.
If you aren't able to conform your payload to the suggested format, you can provide a payload and tell Ascent360 how to locate the data that is relevant to the email.
JSON is the only accepted payload format.
NOTE: If you selected the option to send to an audience, sending a payload with the webhook is entirely optional. If you have merge tags that you want to dynamically swap, you'll want to provide that data in the payload.
Click Provide a Payload, then paste your JSON data. Once pasted, click Validate & Map to enter the mapping interface.
In the mapping interface, you'll see a list of your merge tags on the right side (anything that follows the {{[mergeTag]}} syntax).
- Within the payload, expand the nodes of the JSON tree to locate the relevant data.
- Drag the data from the left side to the corresponding input for that field on the right side. Ascent360 will input the JSON path that will be used to locate the data in subsequent triggers. In order to be dragged, your sample data field needs to have data in it (the interface will not detect nulls).
- Repeat this process for each of the merge tags you need to map.
- You may decide to skip the mapping for CDP Field Merge Tags (See section on Merge Tag Precedence below)
- Other data in the payload that is not identified in the mapping will be ignored for future triggers.
- You may drag into already-filled inputs to overwrite the input or click the green check mark next to the data to clear the input.
Use the Webhook
Once you have decided to follow the suggested schema or provided your own payload example with mapping, close the Trigger section and click the Continue button in the top right. After confirming, Ascent360 will produce a webhook to be used for this email. This webhook is live and can be used immediately.
Whenever you wish to send this email, send an HTTP POST to the webhook provided along with a payload, if necessary. This can be done manually (Postman, for example) or the webhook can be called from an automated process in an external system.
Ascent360 has a size limit of 50MB on the JSON payload. If your payload is properly structured JSON and under the size limit, Ascent360 will respond with a 200 OK and the webhook will remain in a "Ready to Process" state for up to 1 minute and then attempt the send.
NOTE: Providing data through the webhook payload is a great way to leverage data that is either 1) not yet in the CDP (due to overnight timing) or 2) won't be added to the CDP (because it isn't named in the integration/necessary in the CDP).
Data that is passed-in and used in an email through a payload will not be formally added to the CDP as part of this process.
For example, if you are sending a booking confirmation from a PMS or Activities system, Ascent360 still needs to be integrated directly with that system to import the data through our standard nightly process. If all you need to do is send the email and you don't need to see data about the booking on the customer record or in Audience Builder, a direct integration is not needed.
If you wish to leverage a webhook-triggered email for confirmations, you should also double-check that you don't have active recurring sends based on the data flowing in overnight.
Merge Tag Precedence
When receiving a POST to the webhook, Ascent360 will insert dynamic data into the email send based on the order of precedence outlined below:
If your triggered email is sending to an audience:
- Ascent360 will look for mapped data in the payload first and insert into the email. This applies to both custom declared merge tags and CDP Field Merge tags.
- For non-custom CDP Fields that are not found in the payload, Ascent360 will try to fill-in the data from the individual's record in the CDP.
- For merge tags that are not found in the payload or in the CDP, Ascent360 will use the Default Value for that merge tag.
- If there is no payload data, CDP data, or default value, the merge tag will evaluate to a null and appear as a blank space in the email.
If your triggered email is providing the recipient in the payload:
- Ascent360 will look for mapped data in the payload first and insert into the email.
- Sending an email with the recipient in the payload bypasses the CDP (permissions and other data); therefore, all relevant merge tag data for the email should be mapped and provided in the payload.
- For merge tags that are not found in the payload, Ascent360 will use the Default Value for that merge tag.
- If there is no payload data or default value, the merge tag will evaluate to a null and appear as a blank space in the email.
View Webhook History and Resend
You may click the 3 Dots on the Triggered email card in the Design Library to view recent request history, view the webhook for the email, and update the mapping.
This is also where you may wish to attempt the send again via the Resend action. After clicking Resend, the webhook will enter the queue to process again using the data originally received. Ascent360 processes queued webhooks every 60 seconds.
Mapping updating functionality will be added in a future release. For the time-being please duplicate your email if you need to restructure the mapping.
Webhook Trigger Examples
Send to an Audience Example
Below is an example of sending a Webhook-triggered snow report email to an audience.
- This email will be sent to an audience of individuals who have signed up for Snow Reports. Because we're sending to an audience, the merge tag for First Name does not need to come from the payload data and won't be mapped.
The mapping looks like this (Note First Name is not mapped):
Send to a Recipient Example
Below is an example of sending a Webhook-triggered email as a confirmation email for an Activity booking.
After mapping, the resulting email looks like this:
