Outgoing webhooks

What is the meaning of outgoing webhooks?

Outgoing webhooks in Projectrak refer to the mechanism through which the application communicates with external systems when specific events or actions occur within the application. It allows Projectrak to send data or trigger actions in other systems, facilitating seamless integration and interaction between different software platforms.

At present, the only supported event for outgoing webhooks in Projectrak is the update of project field values. This means that when any changes are made to the field values of a project within the application, Projectrak can trigger an outgoing webhook to notify and transmit relevant information to external systems.

How it works

Whenever there is a change in the value of one or multiple fields in a project, Projectrak will send a notification to the configured external system. This notification contains the relevant data about the changes that occurred.

The webhooks in Projectrak are designed to respond to changes made in both system project fields and custom fields added by Projectrak. However, calculated fields of Formula type are excluded and do not trigger webhooks notifications.

To integrate with Projectrak's webhooks, the external system you want to communicate with must have a URL that accepts POST requests. This URL acts as the endpoint where Projectrak will send the webhook notifications containing the change data.

What specific information does the POST request sent by Projectrak's webhook contain?

When a webhook is triggered in Projectrak, it will initiate a POST request to the URL that has been configured by the Jira administrator. This POST request will contain the following data:

Type of event: The specific event that triggered the webhook, such as a field value change.
User information: The user who made the change in the fields, providing details about the author of the modification.
Timestamp: The exact moment when the change was made, allowing you to track the timing of the event.
Project details: The project that has been updated, including its relevant information and identifiers.
Field changes: A list of fields that have been modified, along with the specific modifications made to each field.

Example of request body

{
    data: {
        event: "updated",
        user: "DUMMY-ACCOUNT-ID-4c44-b436-73155f48d985",
        timestamp: 1675182117615,
        project: {
            id: 13647,
            key: "DEMO",
            name: "Demo project"
        },
        fields: [
            {
                id: 12345,
                name: "Budget",
                type: "number",
                value: {
                    current: "23.000",
                    previous: "25.000"
                }
            },
            {
                id: 54321,
                name: "Status",
                type: "status",
                value: {
                    current: "Done",
                    previous: "On track"
                }
            }
        ]
    }
}

Configure an outgoing webhooks

1. Go to Projectrak Administration and then to Outgoing webhooks

2. Click on Create webhook

3. Provide a name to identify the webhook and specify the URL where you want the requests to be made. Additionally, you can also add up to a maximum of 5 headers.

The webhook functionality only supports secure requests under the HTTPS protocol.

4. Save the webhook

Check the outgoing webhook status

In the webhook administration section, you will be able to see all the created webhooks, their last execution, and their latest returned status.

Two types of statuses will be displayed:

OK for all status codes in the 2xx range.
ERROR for the rest of the status codes.

Field value formats

Fields without a value will be represented as "null" for single values or as an empty array for fields with multiple selections.

All field values are strings except the null object. The list below indicates the information that will be send in each field type:

Text: The text.
Text multiple line: The text with the markup.
Number: The number.
Date: The date in format yyyy-mm-dd.
Duration: The duration in milliseconds.
Priority: The name of the priority.
Status: The name of the status.
List: The option name.
List multiple selection: A list of option names.
User: The user account id
User multiple selection: A list of user account ids.
Project: The project id
Project multiple selection: A list of project ids.
Milestones: A list of milestones will all their information as below:
{ data: { event: "updated", user: "DUMMY-ACCOUNT-ID-4c44-b436-73155f48d985", timestamp: 1675182117615, project: { id: 13647, key: "DEMO", name: "Demo project" }, fields: [ { id: 12346, name: "Milestone", type: "milestone", value: { current: { id: 1, date: "2025-02-22", name: "Milestone name - updated", linkedIssuesId: [24, 35] }, previous: { id: 1, date: "2025-02-18", name: "Milestone name", linkedIssuesId: [] } } }, {...} ] } }

HTTP Headers

When your app sends an outgoing webhook to Atlassian Automation or other external services, the request may need to be authenticated to be accepted and processed.

You can accomplish this by adding an HTTP header to your request - a metadata element that tells the receiving service who is making the request and whether they are authorized.

Some endpoints in Jira, especially those used in Automation rules or custom integrations, require a secret token or API key in the header to confirm that the request comes from a trusted source. Without proper authentication, the webhook may be rejected or ignored for security reasons.

Adding custom headers in Projectrak

With Projectrak outgoing webhooks, you can configure up to 5 custom HTTP headers to meet the requirements of external systems like Atlassian Automation or third-party services.

For each header, you can define both a key and a value. The value can be stored as secured, ensuring that sensitive data such as tokens or secrets are protected.

Certain header information is automatically included by default and cannot be altered. This includes:

Content-Type: always set to application/json
Content-Length: calculated dynamically based on the webhook payload.