Introduction

Security Disclaimer

Please note that this feature sends potentially sensitive data in a JSON payload across to a user configured endpoint!

Please review if the data sent via this feature is appropriate for the URI endpoints configured. Only send data to websites/endpoints that you trust or authorise. Consider your Data Protection Regulations.

This feature allows JEMH to send incoming mail processing information as JSON payloads to a user configured URIs CSV list if the URI is validated by the instance’s Jira Allowlist and if the URI Syntax is correct.

JSON Payload information

Interface definition

Please visit our API javadoc page: http://ppl-docs.s3-website-us-east-1.amazonaws.com/JEMH/3.3.50/com/javahollic/jira/emh/api/export/beans/IJEMHInboundMailProcessingWebhook.html for the interface definition.

JSON example

Processing outcomes such as Forward, Dropped, Successful etc… do not prevent the webhook call as the webhook is independent from the event listener.

Successful Outcome

{
    "auditEntryLink": "http://localhost:8080/secure/admin/jemh/JEMHAuditing.jspa?reportId=111",
    "emailSenderAddress": "customer@localhost",
    "processedOutcome": "canHandle",
    "catchEmailAddress": "changeme@thiswontwork.com",
    "auditEventId": 111,
    "processedSuccessfully": true,
    "profileId": 1,
    "createdIssueKeys":
    [
        "JSMIT-42"
    ],
    "emailSubject": "test This is a starting email template, update as required",
    "timestamp": "2021-08-24 16:44:54.397"
}

Unsuccessful Outcome

{
    "auditEntryLink": "http://localhost:2990/jira/secure/admin/jemh/JEMHAuditing.jspa?reportId=20",
    "auditEventId": 20,
    "catchEmailAddress": "changeme@thiswontwork.com",
    "emailSenderAddress": "mailer-daemon@googlemail.com",
    "emailSubject": "This is a starting email template, update as required",
    "filterAction": "drop",
    "filterName": "Whitelisting/Blacklisting filter",
    "filterReason": "Silently dropping (no forward) blacklisted email [type=Profile Blacklist/Whitelist, detail=Email Sender 'mailer-daemon@googlemail.com' was blacklisted due to clause: mailer-daemon@googlemail.com] : from [mailer-daemon@googlemail.com], subject: This is a starting email template, update as required, sent: Sun Jun 19 06:42:26 BST 2011 BlacklistHandling is DROP, returning 'drop' to delete the mail from the queue.",
    "processedOutcome": "drop",
    "processedSuccessfully": true,
    "profileId": 20,
    "timestamp": "2021-08-24 16:51:57.168"
}

Requirements

Webhook Endpoint Requirements

The Webhook must have the following attributes:

Able to consume a POST http request method
Able to parse JSON payload from a request
If response is successful return a response status code of 200
Returns a response with 10 seconds of the initial webhook call!

Jira Allow List

First Ensure that the URI Is validated on your Jira Allowlist via: System > Administrator > Allowlist. Learn about the Allowlist configuration here: https://confluence.atlassian.com/adminjiraserver/configuring-the-allowlist-1014667309.html .

URI Syntax

Ensure that your Webhook URI follows the URI Syntax as per: RFC 3986. For more information please visit: https://en.wikipedia.org/wiki/Uniform_Resource_Identifier#Syntax.

Setup Guide

1) Enable the Webhook

This feature is independent from the Issue Event listener and will continue posting webhooks unless the feature is disabled!

Open the Issue Event Configuration via JEMH > Notifications > Issue Events Section > Edit Icon (Pen Icon).
Enabled the Webhook Enabled checkbox.

2) Add the webhook in the Webhook URI CSV text area.

Once this has been saved JEMH will attempt to send inbound processing data to the configured webhook.

Add a URI which has been validated by your Jira instance’s Allowlist.

3) Ensure that the Webhook added is valid.

Enterprise Mail Handler for Jira Data Center (JEMH) > Use Webhooks > image-20210824-114618.png

4) Validating the webhook is fired via Test Cases and Auditing.

Ensure that the webhook is successful as shown below [SUCCESSFUL].
If the URI in question Invalid please see

Enterprise Mail Handler for Jira Data Center (JEMH) > Use Webhooks > image-20210824-150134.png

Notifications > Webhooks Section

Evaluating invalid webhooks

Hover over the invalid webhook lozenges to see further information on the cause of invalid webhook.

Enterprise Mail Handler for Jira Data Center (JEMH) > Use Webhooks > image-20210824-153242.png

One of the following titles with the error reason will pop up:

URI Not allowed: Verify that the URI is valid for your Jiras Allowlist via Administration > Security > Allowlist see: https://thepluginpeople.atlassian.net/wiki/spaces/JEMH/pages/3296264195/Use+Webhooks#Jira-Allow-List .
URI Invalid Syntax: Verify that the URIs provided follow the URI Syntax see: https://thepluginpeople.atlassian.net/wiki/spaces/JEMH/pages/3296264195/Use+Webhooks#URI-Syntax

Tracking Webhook outcomes via Auditing report

Ensure Inbound Auditing is enabled: https://thepluginpeople.atlassian.net/wiki/spaces/JEMH/pages/1111359489/Use+Auditing#Settings .

The result of URI webhook outcomes is tracked using Incoming Mail Auditing report. The report can be retrieved via:

https://thepluginpeople.atlassian.net/wiki/spaces/JEMH/pages/1111523333/Use+Incoming+Mail+Auditing#Report
https://thepluginpeople.atlassian.net/wiki/spaces/JEMH/pages/1111523333/Use+Incoming+Mail+Auditing#Generate-Support-Zip---SINCE-3.1.2
Or from the webhook itself (If auditing is enabled)

[FAILED] Report Outcome for Webhook

If the webhook outcome is [FAILED] in the affected Incoming Mail Audit Report review the failure message as shown below:

Enterprise Mail Handler for Jira Data Center (JEMH) > Use Webhooks > image-20210824-152435.png

Failed due to Allowlist validation
Failed due to failed URI syntax validation
Failed due to general IO Exceptions. Commonly due to endpoint failing to response within 10 seconds as per https://thepluginpeople.atlassian.net/wiki/spaces/JEMH/pages/3296264195/Use+Webhooks#Webhook-Endpoint-Requirements or endpoint connection closed early.