Webhooks

Last modified: October 10, 2024

Introduction

Webhooks allow you to send information about your licensed Mendix app deployed to Mendix Cloud or Mendix for Private Cloud to an external app or workflow. You can use this to trigger an automated CI/CD workflow when a new change is committed to the Team Server, for example.

Mendix provides webhooks to send project information when the following events happen to your app:

Package upload – when a deployment package is available in the Mendix Portal, including when a package is created from the Team Server
Team Server push – when a new commit is pushed to the Team Server (this will only be triggered if your app is stored in a Git repository)
Alerts – when an alert is triggered for your Mendix app

The webhooks contain a retry mechanism if an error response is received from the endpoint. This helps ensure that the trigger reaches the endpoint.

Webhooks are only available for licensed Mendix apps that are deployed to Mendix Cloud or Mendix for Private Cloud.

Configuring a Webhook

Creating a New Webhook

To set up a webhook, do the following:

Open your app in Apps.
From the navigation pane, open the Webhooks page. On this page, you can see any current webhooks. You can also see whether each webhook is active or inactive. An inactive webhook does not send any payloads to the endpoint.
Click New Webhook.
Enter the following information:
- Webhook Name – This is a name, which you can use to identify the webhook.
- URL – This is the endpoint that will receive the payload when one of the event types selected in Available Events occurs.
- Validation Secret – This is a secret that is shared with the endpoint to verify that it has been triggered by this webhook. For more information, see Verifying Your Webhook below. If you leave this blank, a secret will be generated automatically for you; you can see the generated value any time you return to edit the webhook.
- Available Events – This is the event (or events) that triggers the webhook to send information to the endpoint. You can see more information about these events in the sections below.
- Custom Headers – This is a key-value pair that is sent as an HTTP header to the endpoint.

You can edit or delete an existing webhook by clicking More Options () in the Action column for the webhook you want to change, and then selecting Edit Webhook or Delete Webhook.

Editing or Removing an Existing Webhook

If you select Edit Webhook from More Options () in the Action column for a webhook you want to change, the following actions are available:

Update Webhook Name, URL, or Validation Secret, and click Save to save the changes.
Add or delete custom headers, and click Save to save the changes.

You cannot change the value of an existing custom header. If you want to change the value, delete the existing header and add a new one with the same key.

If your webhook has a custom header with the key “Authorization”, this is considered sensitive and thus does not display in the Custom Headers section on the Webhooks page. However, it can be seen in the webhook response if you test that webhook.
Click Test Webhook to send a test payload to the endpoint specified under URL.
Click (De)activate Webhook to deactivate an active webhook or activate an inactive webhook.
Click Delete Webhook to completely remove the webhook.

Outgoing IP Addresses for Webhooks

If you want a Mendix webhook to contact one of your firewalled servers, it is recommended to safe list the IP addresses from which the webhook requests will originate.

Mendix webhooks use the following static IP addresses:

18.194.214.35
3.64.82.159
52.59.169.126

Mendix maintains the current outgoing IP addresses as much as possible. However, these addresses may occasionally change for operational reasons. At least 48 hours before any changes, Technical Contacts will be emailed and a notification will be listed on Mendix Platform Status.

Webhook Headers

Every POST payload contains the following delivery information as part of the header:

connection – close, indicating that there is no further information for the HTTP request
content-length – the size of the HTTP request in bytes (for example, 475)
webhook-signature – the signature of the webhook in the format <version>,<signature> (for example, v1,Ay2spGBdE7i6OzNkFgTDnGfqgZT0WonCFoBMt8V3YiQ=); for more information, see Verifying Your Webhook below
webhook-id – a unique identifier for this webhook trigger (for example, msg_2M605iBQRge9hTgpYg7fKXQubaw)
user-agent – the user agent used to process this trigger
webhook-timestamp – the time the webhook was triggered (for example, 1677072542)
content-type – application/json
accept – */*
host – the host part of the endpoint URL (for example, gitlab.com)

You can also add your own custom headers. For more information, see Configuring a Webhook.

The order of these headers is not guaranteed.

Verifying Your Webhook

Once you set up a webhook, make sure to verify that your endpoint has received a payload from Mendix and that the request has not been generated or intercepted by a bad actor.

This verification is enabled through the webhook-signature that is sent in the webhook header. It is generated using the Validation Secret you provided when you set up the webhook in combination with the payload of the trigger using HMAC-SHA256 authentication.

To verify the signature, you need to reconstruct it and then compare it with the webhook-signature in the webhook header. This is the general process:

Construct a string containing the signed content, which is the {webhook-id}.{webhook-timestamp}.{webhook payload}. Note the full stop (.) between each element.
Calculate the webhook-signature using the HMAC-SHA256 function for your language and the Validation Secret you set up for the Webhook.

Ensure the result is base64 encoded. For example, in a bash script, this might be as follows:

WEBHOOK_ID= #from the header
WEBHOOK_TIMESTAMP= #from the header
PAYLOAD= #payload of the message
VALIDATION_SECRET= #set when creating the webhook in the Mendix Portal

# To generate the signature:
printf '%s.%s.%s' "$WEBHOOK_ID" "$WEBHOOK_TIMESTAMP" "$PAYLOAD" | openssl dgst -sha256 -binary -hmac "$VALIDATION_SECRET" | openssl base64

Compare calculated-signature with webhook-signature to ensure that they match. Note that the webhook-signature is prefixed by a version and a delimiter. For example, the signature for v1,f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8= is just f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8=.

When verifying your webhook signature, keep the following in mind:

The signature list webhook-signature usually contains a single signature. If there is more than one signature, use the first signature, which is calculated using the latest validation secret.
To prevent timing attacks, use a constant-time string comparison method.
To protect against timestamp attacks, where old webhook payloads are sent to your endpoint, verify that webhook-timestamp is within your tolerance for the current system time.

Verifying Your Webhook Using Mendix

You can use Mendix to verify your webhook; the Community Commons module has functions that you can use for this. To make use of this functionality, follow the steps below:

Confirm that your app contains the Community Commons module.
Retrieve a list of System.HttpHeader objects over the association $HttpRequest/HttpHeaders using the HttpRequest from the webhook.
Obtain the webhook-id, webhook-timestamp, and webhook-signature headers by using a Find by expression List operation on the list of System.HttpHeader objects. You can use an expression like toLowerCase($currentObject/Key) = 'webhook-id' and extract the /Value attribute.
Create a string variable consisting of the webhook-id, webhook-timestamp, and the Content attribute of the $HttpRequest separated by periods (.). Here is an example: $WebhookId + '.'+ $WebhookTimestamp + '.' + $HttpRequest/Content.
Hash the string variable you just created using the Community Commons action Generate HMAC SHA256 hash and the validation secret you set when creating the webhook.
Prefix this hashed string with the prefix from the webhook signature (for example, v1,).
Compare the string you have created (the hash and the prefix) with the webhook-signature you retrieved from the list of System.HttpHeader objects earlier. If the two strings match, then the webhook call is valid.

Package Upload to the Mendix Portal

When you upload a package to the Mendix Portal (including creating a package from the Team Server), and the webhook responds to the event On package upload, request content is sent to the configured endpoint. The request content contains a payload with the following format:

{
  "eventType": "package.uploaded",
  "modelVersion": "0.0.19.62e3d711",
  "name": "main-0.0.19.62e3d711.mda",
  "projectId": "f60650eb-230a-4419-a6af-b3668fc82d5d",
  "runtimeVersion": "9.18.1.54902",
  "uploadTime": "2023-02-23T10:25:21.3896Z",
  "uploaderId": "4bcafd1c-dac8-4335-b401-06ebe86f7851"
}

If you need a specific package ID for an API call, use the Retrieve Packages call of the Build API to find all the packages. Then, use the name value to find the latest package information for your desired package.

Make sure to use the correct key names when using this payload information to call other Mendix APIs. The data may be labeled differently in the API.

Teamserver Push (Git)

When you push a model change to the Git Team Server, and the webhook responds to the event Teamserver push (Git), request content is sent to the configured endpoint. The request content contains a payload with the following format:

{
  "after": "4b76061182bf183281b5107cd753c6071ed00040",
  "before": "0b9cb7a3e9a5ccfffa6c79435441999543ccb8c9",
  "branchName": "main",
  "commits": [
    {
      "authorDate": "2022-12-08T16:15:52+01:00",
      "authorEmail": "uria.abrams@example.com",
      "authorName": "Uria Abrams",
      "id": "4b76061182bf183281b5107cd753c6071ed00040",
      "mendixVersion": "9.20.2.1234",
      "message": "Commit the changes",
      "relatedStories": [
        {
          "id": "MS-1234"
        }
      ]
    }
  ],
  "eventType": "teamserver.push",
  "projectId": "9bcd62a6-9c19-4c7f-a5ae-49182c67f80f",
  "repositoryType": "git"
}

The after, before, and id values are Git commit hashes. In most cases, you will want to use the after hash (the last commit on the branch).

Make sure to use the correct key names when using this payload information to call other Mendix APIs. The data may be labeled differently in the API.

Alerts Webhooks

When an alert is triggered for your Mendix app, a payload with the following format is sent to the configured endpoint.

{ 
  "app_name": "your-app-name",
  "environment": "your-environment-name",
  "environment_id": "n90c72er-344e-4a26-8efd-e0695234b465",
  "id": "73eb456a-10d4-4821-ae58-31e4a49753ca",
  "message": "INFORMATIONAL: Runtime heartbeat is okay.",
  "service": "Application Status",
  "severity": "Recovery",
  "timestamp": "2023-08-18T08:11:22.586000+00:00",
  "url": "https://your-mendix-app.mendixcloud.com"
}

The severity key name from the above JSON can have following values:

Ok
Warning
Critical
Recovery

For details on receiving alerts, see Receive Environment Status Alerts.

Logging

You can see log messages in the Mendix Portal indicating when your webhooks were created or updated.

Mendix Cloud does not create a log message when a webhook is triggered.