How to Set Up Email Notifications for Workflow

Problem Statement

Reviewers need to know when an item in a workflow stage requires their action. Uniform webhooks can subscribe to the workflow.transition event and forward it to an email API, so reviewers get notified automatically.

Solution

This example uses mailersend.com because it has a free tier, but any email service with an HTTP API works.

1. Create the webhook

Create a webhook subscribed to the workflow.transition event, pointing to the email API endpoint, e.g. https://api.mailersend.com/v1/email.

2. Add authentication

If the email API requires authentication, create an API token and set the Authorization header in the webhook's Custom Headers section.

3. Enable webhook transformation

Add a transformation to compose the email from the webhook payload: who triggered the workflow, the stage, and a link to open the content. Adjust the sample below to your email service.

/**
 * @param webhook the webhook object
 * @param webhook.method destination method. Allowed values: "POST", "PUT"
 * @param webhook.url current destination address
 * @param.webhook.eventType current webhook Event Type
 * @param webhook.payload JSON payload
 * @param.webhook.cancel whether to cancel dispatch of the given webhook
 */
function handler(webhook) {
  webhook.method = 'POST'
  const subject = `Workflow notification from Uniform project`
  const initiatorName = webhook?.payload?.initiator?.name ?? 'Someone'
  // checks the name of the workflow stage
  const isApproved = webhook?.payload?.newStage?.stageName?.includes('Approved') ?? false
  const html = isApproved
    ? `Hi, <br /> There is a workflow notification from Uniform project<br /> $ {initiatorName} has approved the $ {webhook?.payload?.entity?.type} in : <br /> <a href="$ {webhook?.payload?.entity?.url}">$ {webhook?.payload?.entity?.name}</a> `
    : `Hi,  <br /> There is a workflow notification from Uniform project<br /> $ {initiatorName} has requested approval for the $ { webhook?.payload?.entity?.type} below: <br /> <a href="$ { webhook?.payload?.entity?.url}">$ {webhook?.payload?.entity?.name}</a> `

  webhook.payload = {
    from: {
      email: 'hello@12345-mailer.mlsender.net',
      name: 'MailerSend',
    },
    to: [
      {
        email: 'reviewer@yourcompany.com',
        name: 'John',
      },
    ],
    subject: subject,
    html: html,
    personalization: [
      {
        email: 'reviewer@yourcompany.com',
        data: {
          company: 'MailerSend',
        },
      },
    ],
  }
  return webhook
}

Resources

• Workflows

• Webhooks