Skip to main content
All CollectionsPayhawk LabsBeta featuresWorkflow automations
Configuring external approvals in Jira

Configuring external approvals in Jira

Set conditions for communication between Jira and Payhawk to integrate the external system step in your Payhawk approval workflow.

Payhawk avatar
Written by Payhawk
Updated over a week ago

As a Payhawk administrator for your company, you can integrate Jira Automation with Payhawk's external workflow step capabilities.

With Jira Automation, you can also set up conditions based on which Payhawk communicates with Jira, so that the data is sent to the external system and stored for future use in any relevant process.

The Automation module in Jira is a no-code feature allowing Global or Project Admins to create automation rules, thus enabling teams to automate their processes and keep Jira up to date.

About this guide

This guide will walk you through the sample use case scenario to showcase the following steps:

  1. Define custom fields in Jira to save the callback URLs to approve or reject from Jira.

  2. Set up the incoming webhook configuration in Jira allowing Payhawk to send data to the external system.

  3. Create the external approval step in Payhawk.

  4. Set up the callback configuration in Jira allowing the external system to send data to Payhawk.

Step 1: Predefine the custom callback fields

Payhawk provides Jira with 2 callback URLs for approving or rejecting a workflow step in Payhawk. To enable communication between the two systems, these URLs must first be defined as custom callback rules. They are then stored in the Jira issue (ticket) to support rule configuration.

Additionally, you can create other custom fields as needed for your internal processes by following the same approach described below:

  1. Go to Jira > Project settings > Fields > Add field.

    1. In the dialog that opens, select Create a new field.

    2. Add the name for the field, for example, Approve URL.

    3. Select type URL.

    4. (Optional) Add the description for the field.

    5. To define the Reject URL custom field, follow the same steps.

  2. Go to Project settings > Issue types and select the desired issue, for example, Contract.

    1. In the Fields dialog, drag and drop the desired fields to the issue type.

    2. Click on Save changes.

Step 2: Setting up the incoming webhook configuration

To enable the communication from Payhawk to Jira, you need to use Jira Automation to define the rule and set the incoming webhook configuration:

  1. Go to Jira > Project Settings > Automation > Create rule.

  2. To confgure the trigger:

    1. Click on When: Add a trigger field.

    2. Find Incoming webhook.

  3. In the Incoming webhook dialog that opens:

    1. The Webhook URL endpoint is automatically generated after you have saved the rule.

    2. The Secret field is automatically generated after you have saved the rule. It contains the secret token value for the connection. Payhawk has to call this endpoint with the X-Automation-Webhook-Token header key and token value.

    3. Under Work item criteria, select the No issues from the webhook option.

  4. To configure the condition and the consecutively triggered action:

    1. Click on Add component.

    2. In the dialog that opens, select THEN: Add an action.

    3. On the next screen, find the Create issue action.

  5. In the Create issue dialog that opens:

    1. Select the project in which you'll create the issue, for example, Legal.

    2. Select the type of the issue, for example, Contract.

    3. Click on the Choose fields to set drop-down menu to add the custom callback fields defined above. As a result, the selected fields are added to the list of inputs in the dialog.

    4. Fill the data in the Summary and Description fields by using the key attributes from the sample payload in Payhawk:

      1. In the Payhawk web portal, go to Settings > Workflows.

      2. Click on Edit workflow for the desired workflow.

      3. Click on + (plus) and select Approval in external system.

      4. In the dialog that opens, click on Show sample payload.

      5. Back in Jira, add the desired attributes by following their {{webhookData.[attribute]}} established convention. For example, to refer to the title, update the string to {{webhookData.title}}.

  • If you automate an approval workflow for purchases, the sample payload data will differ.

  • The information from the webhook alone may not always be sufficient. Payhawk might need to make an additional call from Jira to the Payhawk Developer API to retrieve, for example, the actual number of the purchase document.

Step 3: Adding the external approval step in Payhawk

Now you need to add the external approval as workflow step in Payhawk by using the data from the Jira Automation configuration you have already set:

  1. In the Payhawk web portal, go to Settings > Workflows.

  2. Select the desired workflow and click on Edit workflow.

  3. Go to the desired step, click on + (plus), and select Approval in external system. This step will allow you to finalize the setup with the callback trigger in Jira later on.

    Alternatively, you can select the Send notification option. In this case, Payhawk will just notify the external system and continue the workflow without waiting for an approval.

  4. Click on the new step to open its configuration dialog.

  5. Add the following settings:

    1. In the Outgoing URL field, add the Webhook URL value from the Incoming webhook configuration in Jira.

    2. In the Header > KEY field, add X-Automation-Webhook-Token.

    3. In the Header > VALUE field, add the Secret token value from the Incoming webhook configuration in Jira.

    4. The Approval URL and Rejection URL values are automatically generated by Payhawk.

  6. When done, click on Save and, then, on Publish workflow.

Step 4: Setting up the callback configuration

Now you need to complete the external system configuration and set up the callback that will enable Payhawk to detect any changes in the external approval step based on updates in the Jira task status.

  1. Go to Jira > Automation > Create rule.

  2. To configure the trigger:

    1. Click on When: Add a trigger field.

    2. Find Issue transitioned.

  3. In the Issue transitioned dialog that opens:

    1. In the From status field, select the task statuses from which the system will detect a change - for example, TO DO.

    2. In the To status field, select the status which will trigger the update in the approval step in Payhawk, for example, DONE.

  4. To configure the condition and the consecutively triggered action:

    1. Click on Add component.

    2. In the dialog that opens, select THEN: Add an action.

    3. On the next screen, find the Send web request action.

  5. In the Send web request dialog that opens:

    1. Under the Web request URL field:

      1. Click on {} to display the Smart Values dialog. Select the Custom fields tab.

      2. Select the desired custom Payhawk fields, for example, Approve URL.

      3. Copy the ID of the custom field and paste it in the Web request URL field.

      4. Follow the same steps to add the Reject URL custom Payhawk field.

    2. Under Headers > Key, fill in the X-Payhawk-ApiKey: token.

    3. Under Headers > Value, fill in the secret token generated by Payhawk:

      1. Go to Settings > Integrations.

      2. Find the respective Workflows API Key and click on Manage.

      3. When the dialog opens, click on Copy to copy its value.

Useful resources

Did this answer your question?